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DESQview API Reference Manual 


This is the primary source of information 
about the DESQview API. It contains all you 
need to know to write assembly language pro- 
grams that take full advantage of DESQview’s 
capabilities. The Reference manual comes with 
an include file containing symbols and macros 
to aid you in development. AVAILABLE NOW! 


DESQview API C Library 


The DESQview API C Library provides 
C Language interfaces for the entire set of API 
functions. It supports the Lattice C, Metaware 
C, Microsoft C, and Turbo C compilers for all 
memory models. Included with the C Library 


package is a copy of the API Reference 
Manual and source code for the library. 
AVAILABLE NOW! 


DESQview API Debugger 


The DESQview API Debugger is an 
interactive tool that enables the API pro- 
grammer to trace and single step through 
API calls from several concurrently running 
DESQview-specific programs. Trace infor- 
mation is reported symbolically along with 
the program counter, registers, and stack at 
the time of the call. Trace conditions can be 
specified so that only those calls of interest 
are reported. AVAILABLE NOW! 
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Introducing 
DESQview 2.0 
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Bringing 
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to DOS 


DESQview API Panel Designer 


The DESQview API Panel Designer is an 
interactive tool to aid you in designing win- 
dows, menus, help screens, error messages, 
and forms. It includes an editor that lets you 
construct an image of your panel using simple 
commands to enter, edit, copy, and move text 
as well as draw lines and boxes. You can then 
define the characteristics of the window that 


will contain the panel, such as its position, size, 


and title. Finally, you can specify the locations 
and types of fields in the panel. 

The Panel Designer automatically generates 
all the DESQview API data streams necessary 
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to display and take input from your panel. 
These data streams may be grouped together 
into panel libraries and stored on disk or as 
part of your program. AVAILABLE NOW! 


DESQview API Pulldown 
Menu Manager 


The DESQview API Pulldown Menu 
Manager is an interactive tool to aid you in 
designing pulldown menus. This DESQview 
API tool assists you in giving your DOS 
program an OS/2-like look and feel. 
AVAILABLE OCTOBER 88 
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ichael Abrash has 

coined a new verb to 

describe what he does 

for a living: He “zens” 
86-family machine code. Yes, he 
programs in assembler, but his 
methods differ so markedly from 
standard practice that he feels a 
new word is called for. 

How one “zens” is hard to de- 
scribe—though Ill try—but I’m 
convinced that it works, having 
seen an EGA-based graphics win- 
dowing interface that Michael 
wrote where a moving window 
doesn’t “blank out” but retains its 
contents, and moves smoothly 
from top to bottom, without flicker 
or any annoying refresh “swoop.” 

And oh, right, I forgot to tell 
you: This was on a 4.77-mHz 8088 
machine. 

The aim of zen coding is to pro- 
duce the fastest, most compact ma- 
chine code possible. Following are 
the principles Michael uses to 
achieve this aim. 

Love the machine. I was tempted 
to say, “Know the machine,” but 
knowledge, while essential, isn’t 
the germ of the principle. Too of- 
ten we strive to know our hard- 
ware like we’d know an enemy, 
just in order to avoid getting 
trounced. The aim of zen coding 
is to wrap the program closely 
around the hardware so that every 
element of the hardware works for 
us, not against us. First of all, this 
means grabbing every available 
reference on PC hardware and 
digesting it down to the status bit 
level and even further whenever 
you can. But more than that, it 
means looking at the complexity 
of the hardware as an opportunity 


BEGIN 


The zen factor 


Jeff Duntemann 


to fine-tune, and not as a tar pit to 
die in. 

Once you know the hardware, 
use it. Write to the bare metal at 
every opportunity. Portability goes 
out the window because you're 
writing for this machine—next 
year you can begin the process 
again for some other machine. 
Nothing says this kind of develop- 
ment comes cheap. 

Above all, love it. If you can’t 
quite shake the notion that this is 
somehow playing dirty, you’re not 
cut out for zen coding. 

Assume nothing. Optimizing by 
dead reckoning—that is, by writ- 
ing a cycle count next to each in- 
struction, adding them up, and 
then seeing what you can pull 
out—doesn’t work. It doesn’t work 
because instruction cycles aren’t 
the whole story. Every machine 
has “cycle-stealers,” including 
memory wait states, video wait 
states, and DMA refresh delays, 
that skew the total in ways that are 
nearly impossible to predict on 
paper. Furthermore, once you fac- 
tor in the nondeterministic effects 
of the filling and purging of the 
prefetch queue, the paper chase 
is simply over. You cannot know 
how time-efficient a given solution 
will be unless you go in and mea- 
sure the solution in action. Forget 
how fast a snippet of code must 
be—go in and see how fast it is. 

Look at all possible solutions. 
Some folks build mini-interpret- 
ers. Others optimize by giving 
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over subroutine calls and putting 
repeated instances of the same 
routine in one long sequence. Still 
others will do anything to keep 
values floating in registers. The 
art of zen coding requires the 
coder to keep an open mind and 
have a feel for which solution is 
right for the problem at hand. 
Whether we realize it or not, we 
often recast a problem in familiar 
terms to conform to our familiar 
solutions. Keeping things in reg- 
isters may help—but eliminating 
subroutine calls by keeping code 
inline may help more. If you don’t 
try, you can’t know. 

None of this is easy. Nor is the 
above summary the final word: 
Michael emphasizes the impor- 
tance of right-brain thinking to tie 
it all together, and that may be the 
toughest part of all. Still, I’ve per- 
suaded him to take a shot at de- 
scribing his methods in a book, 
and with some luck, The Zen of As- 
sembler will appear next year. 

One thing is clear: There 
comes a point when conventional 
methods in conventional lan- 
guages fail us. At that point the 
only alternative is assembly lan- 
guage, where the programmer be- 
comes the code generator and the 
rules get turned on their head. 
Zen coding throws away the pre- 
cepts of breaking down a problem 
into independent modules, and 
demands that the programmer 
embrace the problem as an or- 
ganic whole in the quest for a uni- 
fied, optimal solution. Not every- 
one can do it—but our very com- 
petitive industry will be very good 
to those who can. 


Opinions expressed in this column are those 
of the editor and do not necessarily reflect 


the views of Borland International, Inc. 


Best performance in a pppoe role. 
Because your time is more valuable then ever, Blaise Computing presents POWER SCREEN™ 
the new high performance screen management system designed to support your own creative 
programming efforts. 


POWER SCREEN provides reliable, lightning fast data entry screens and 
menus to create your own sophisticated window oriented applications. 
It allows you to design screens exactly as you want them to appear in your 
final application. Screens are efficiently stored in a file so they can be 
used by your application or later modified without program code changes. 


PAINT, the screen painter included with POWER SCREEN, has the 

appearance and performance of the popular integrated programming 
language environments. It lets you design and modify screens, and 
define and format fields. All VGA, EGA and monochrome text modes, 
attributes and colors are supported. 


The POWER SCREEN Runtime Library allows you to construct 
screens in memory, display screens in windows and read and write 
data to fields within the screen. All screens and menus are window- 
oriented, so they can be stacked, removed or moved on the physical 

screen. You can access screens field-by-field or a whole screen at a 
time. POWER SCREEN takes care of field input editing, data and 
range checking, and data formatting. 


POWER SCREEN out-performs the runners-up with a dazzling 
display of capabilities FEATURING: 


Screens that can be larger than the physical 
screen, with just a portion of the screen displayed within a window. 
Write to any screen any time, even if it is not visible. Automatic 
physical screen update. 


Create help text on a field-by-field basis 
or for the entire screen with a window-oriented help facility. 


Install them so your application gains 
control when a field is entered, exited and between keystrokes. 


Supported for all standard data types. 


Subject only to the amount of available 
memory. 


Fully configurable field editing keys. 


POWER SCREEN includes PAINT, the POWER SCREEN 
Runtime Library, as well as other utilities for creating help 
files and maintaining and documenting your screen data- 


base files. Language interfaces with source code are included 
for C, Turbo Pascal 4.0 and QuickBASIC. 
The package is accompanied by a fully-indexed comprehensive User Reference 
describing POWER SCREEN procedures and utilities. Complete example programs 
are supplied on the diskettes. 
POWER SCREEN requires an IBM PC, XT, AT, PS/2 or close compatible and DOS 2.00 
or later. To write POWER SCREEN applications, you need one of the supported com- 
pilers: Turbo C, Microsoft C (4.00 or later), QuickC, Turbo Pascal (4.0 or later), 
QuickBASIC (4.0 or later). Interfaces for all supported compilers are included 
with POWER SCREEN. 
Blaise Computing: We've passed the screen test so you 
won't have to. 


Blaise Computing has a full line of support products for both 
Pascal and C. Call today for your free information packet. 
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8129, 00 
Windows; menus; TSRs: intervention cod 
screen handling and EGA 43-liné text mode 
support; direct screen access; DOS file 
handling and more. Specifically designed for 
Microsoft C 5.0. and QuickC. 


$175.00 
Full featured interrupt driven support fort up 
to four COM ports. I/O buffers up to 64K; 
XON/XOFF; hardware handshaking; up to 
19.2K baud; modem control and XMODEM 
file transfer; For Microsoft C and Turbo 


$129. 00. 
Full spectrum of general service utility func-— 
tions including: windows; menus: memory 
resident applications; interrupt service rou- 
tines; intervention code; and direct video ~ 
access for fast screen handling. For Turbo C.. __ 


yPilo $49.95. 
“Super-batch” program. Create batch files ~ 
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usage. 
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NOT PLATONIC 


I want to correct an historical er- 
ror on page 67 of your March/ 
April, 1988 issue. Keith Weiskamp 
states that Plato is the “Father of 
Logic.” Nonsense. Plato had the 
first comprehensive organized 
philosophic system, but logic was 
not one of its attributes. It was Pla- 
to’s student, Aristotle, who was the 
true founder of logic (via his Prior 
and Posterior Analytics for the 
most part). This is well known and 
easily verifiable by reading Plato 
versus Aristotle, whose philoso- 
phies are very much opposed for 
the most part. Plato touted the 
philosophy of “two worlds”; Aris- 
totle rejected this. Plato believed 
that all knowledge is innate, exist- 
ing in people at birth, which is 


DIALOG 


Slander not Aristotle; remember the 
RESTART; and how tightly is Bruce 
coupled to his parachute? 


hardly conducive to logic or any 
logical theory of knowledge. Aris- 
totle completely rejected this as 
well, stating that all babies are 
born “tabula rasa,” or like a blank 
slate, and acquire all knowledge 
after birth. Plato uses all sorts of 
illogical premises and arguments. 
Plato was basically a mystic and 
the founder of the idea of totali- 
tarianism, via The Republic. So 
don’t ascribe logic, of all things, to 
Plato. Give credit where credit is 
due—to Aristotle. 


—Philip Oliver 
Indianapolis, IN 
We sincerely hope that the old chap 
will forgive us. 
—Jeff Duntemann 


SILICON NOSTALGIA 

First let me thank you for what is 
becoming a very excellent publi- 
cation. There is little in the micro- 
computer field today (other than 
the continuing quality of Byte) that 
offers genuine technical content 
instead of business chatter. 

However, at the risk of being 
accused of nit-picking, I must take 
issue with Jeff Duntemann’s state- 
ment (“Exploring the Interrupt 
Vector Table,” May/June, 1988) 
that “Until the development of the 
8086 and 8088, all interrupts were 
hardware interrupts.” 

Evidently Mr. Duntemann has 
never programmed a Z80 or 8080 
chip. Both of these older proces- 
sors have a software interrupt ca- 
pability very similar to that of the 
8086/88 family, although they 
only have eight vectors in contrast 
to the 255 available on later chips. 
I will not make any statements 
crediting the 8080 as the first mi- 


6 TURBO TECHNIX September/October 1988 


croprocessor to offer this feature, 
since it may have existed even 
earlier. 

MS-DOS is not the first operat- 
ing system to take advantage of 
software interrupts, either. They 
were used at least as early as the 
CP/M-80 operating system, and 
the LDOS/LS-DOS operating sys- 
tems used on the Z80 made exten- 
sive use of software interrupts 
long before MS-DOS was intro- 
duced. 

Many writers today fall into the 
common trap of assuming that 
IBM, Intel, and Microsoft were in- 
novators who virtually invented 
microcomputers and operating 
systems. This simply isn’t the case. 
They all adapted concepts and 
hardware that were already devel- 
oped and in use at that time. 

—Gary Lee Philipps 
Chicago, IL 


Nay, nay; I was there. Only just last 
week Mr. Byte snuck into the garage 
and lifted his leg on my cobwebbed 
IMSAI 8080 S100 box, which I can’t 
sell or even give away. What passes 
for a software interrupt on the 8080 
is the mysterious RESTART instruc- 
tion, which I never used because none 
of my books ever bothered to explain 
what it was or how it worked. RE- 
START 1 was roughly equivalent to 
an 8088 INT 1, except that RE- 
START 1 transferred control to a 
JMP instruction in a calculated loca- 
tion in low memory, rather than to an 
address contained in a vector table. 
8080 hardware interrupts worked in 
much the same way, so while it’s true 
continued on page 8 


Multiple Screens... 
give you the big picture. 


BLAISE COMPUTING INC. 


Presenting POWER SCREEN, a new 
high performance screen manage- 
ment system by Blaise Computing 
which provides everything you 
need to create lightning-fast win- 
dow oriented applications. 

Paint the screens exactly as you want 
them to appear in your final applica- 
tion. POWER SCREEN allows you to 
construct screens 
in memory, dis- 
play screens in 
windows and 
read and write 
data to fields 
within the screen. 
All screens and 
menus are win- 
dow oriented, so 
they can be stack- 
ed, removed or 
moved about on 
the physical 
screen. You can 
access screens 
field-by-field, or a whole screen at a 
time. POWER SCREEN takes care of 
field input editing, data and range 
checking, and formatting of the data. 


POWER SCREEN has the appearance 
and performance of the popular in- 
tegrated programming language en- 
vironments. It helps you to design and 
modify screens, define fields and how 
they are formatted, specify range 
values and field output masks. All at- 
tributes and colors are supported in- 
cluding all VGA, EGA and 
monochrome text modes. 


More than just a code generator, screens 
are stored in a Runtime Library that you 
can later access and modify without 
program code changes. 


-Virtual screens! 

-Context sensitive help! 

-Total control over every keystroke during data entry. 
-Write to any screen any time, even if it is not visible. 
-Automatic physical screen update. 

-Range checking is supported for all standard data types. 


POWER SCREEN supports a variety of 
languages including Microsoft C 5.0 
and QuickC, Turbo C, Turbo Pascal 4.0, 
and QuickBASIC. 


POWER SCREEN includes The Norton 
Guides Online Instant Access Program 
ready to use with our database of on- 
line help information. 


-Number of screens is limited only by the amount of 
available memory. 

-Detects which display adapter and monitor are used. 
-Fully configurable field editing keys. 

-Well documented source code. 

-No royalty payments. 


This package is accompanied by a fully- 
indexed comprehensive User 
Reference manual describing POWER 
SCREEN procedures and utilities. 
Complete example programs are sup- 
plied as wellas utilities for creating help 
files and maintaining and document- 
ing your screen database files. 


POWER SCREEN requires an IBM PC, 
XT, AT, PS/2 or close compatible and 
DOS 2.00 or later To write POWER 
SCREEN applications, you need one of 
the supported compilers: Turbo C, 
Microsoft C (4.00 or later), QuickC, 
Turbo Pascal (4.0 orlater), QuickBASIC 
(4.0 or later). Interfaces for all sup- 
ported compilers are included with 
POWER SCREEN. 
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Carries a complete line of 
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tools including the Blaise 
Computing products for C 
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that RESTART acted like a software 
interrupt, nobody ever called it a soft- 
ware interrupt, and very few people 
ever made the connection. 

Flipping through the yellowing 
pages of 1978-vintage books on the 
8080 CPU and S100 bus last night 
(I wire-wrapped my first machine in 
1976 and am by no means a newcom- 
er to this business) made me appreciate 
how much more we know about our 
hardware and our operating systems 
than we did ten years ago. The 8080 
and CP/M-80 were much more potent 
than we ever appreciated, because back 
then we were working almost blind. 
As I said in my January/February ed- 
itorial, much of the power of the 8088 
and DOS stems from the depth of our 
understanding of them. Had I known 
what RESTART was in 1979, I 
would have used it, and I would have 
explained to others how to use it, but 
the 8080 and CP/M vanished before 
the industry’s understanding of them 
achieved the critical mass that the 
8088 and DOS enjoy today. 


—Jeff Duntemann 


MAKING TIME 


I read Mr. Ron Sires’ feature “A 
Memory Resident Clock Utility,” 
May/June, 1988, with great inter- 
est, since I write numerous 
memory-resident programs. Mr. 
Sires described a manual proce- 
dure for determining the size of 
a program. He did a compile with 
the map option set in order to de- 
termine the size of the 
CLOCK.EXE program from the 
TLINK map. The value 1298H for 
_.BSSEND was rounded up to 
1300H and then divided by 16 giv- 
ing the value 130H for the pro- 
gram size. This value was then 
used in his main() function in the 
keep(0, 0x0130) statement. This 
manual procedure could be re- 
placed with an automatic proce- 
dure by changing the original 
KEEP statement to the following: 
keep(0, 

(Cunsigned int)sbrk(0)+15)/16); 
Thus, if the size of the program 
changes, the second parameter to 
the keep function will automati- 
cally change to compensate. Note 
that the return value from the 
sbrk function is cast to an un- 
siggned int so that values greater 


than 7FFFH will be processed cor- 
rectly. The sbrk function is de- 
scribed in detail in the Turbo C 
Reference Guide, page 44. 
—Alan Cohn 
Irvine, CA 


Neat hack, Alan. Thanks; I'd been 
looking for a way to do that. I’ve 
tested it in CLOCK.C and it works 
fine, and is a good general way to do 
the program-sizing job I described how 
to do manually. The only caution is 
that I’ve only tested it under the Tiny 
code model, and sbrk really doesn’t 
make sense under any but the Tiny 
and Small code models, since it de- 
pends on there being only a single 
data segment in the program. 

—Ron Sires 


MAC SCENE 


Even though I do all of my pro- 
gramming on an Apple Mac+, I 
find all of the articles in TURBO 
TECHNIX help me to write better 
code. The best features of the 
Borland programming languages 
are that they are complete, up to 
date, similar in format and are 
thoroughly supported by good tu- 
torials specific to the languages. 
Tutorials like the Borland/ 
Osborne-McGraw Hill books are 
nonexistent for the Macintosh, 
and if there is anything that a be- 
ginner needs for the Macintosh, 
it’s a good tutorial specific to the 
language. I do have Borland’s 
Turbo Pascal Tutor for the Macin- 
tosh and it is complete but lacks 
the short programming examples 
that the Borland/Osborne- 
McGraw Hill books use to help a 
programmer get started. (I realize 
that in a book as big and complex 
as the Turbo Pascal Tutor this is 
not possible.) 

I would like to see a Borland 
Turbo C and Turbo Basic, both 
supported by Borland/Osborne- 
McGraw Hill tutorials, for the 
Macintosh. Following that, a 
TURBO TECHNIX for the Mac 
would be great. Is there any pos- 
sibility of that in the near future? 


—Robert Orthman 
Boulder, CO 


Well, gee, given endless funds we can 
do almost anything—but software 

R & Dand magazine publishing are 
two of the most expensive endeavors 

I can think of. Borland’s commitment 
to Macintosh developer tools is secure, 
and we can’t be much more specific 
than that. As for a TURBO TECH- 
NIX for the Mac—that might be a 
long, long wait. In the meantime, you 
can’t do much better than Mac Tutor, 
The Macintosh Programming Journal 
(P.O. Box 400, Placentia, CA 
92670). They publish monthly at 
$30/year, with 86 pages per issue. 
Their motto is “No fluff,” and they 
mean it, with the (minor) downside 
that they don’t publish what we would 
consider Square One material. 

As for tutorial books, help is com- 
ing. The venerable Scott, Foresman & 
Company has concluded an agreement 
with Borland very similar to the one 
between Borland and Osborne- 
McGraw Hill, to copublish a series of 
books on Borland’s Macintosh prod- 
ucts. All Mac products, including the 
business products, will be covered, 
and the books will begin to appear 
later this year. Watch for Complete 
Macintosh Turbo Pascal by Joseph 
Kelly as the first programming tuto- 
rial in the series. There will be more. 
If there were another two or three of 
me, I'd write one myself. 

—Jeff Duntemann 


AFTER YOU, BRUCE 


Bruce Webster is an interesting 
man; I had the pleasure of jump- 
ing out of an airplane with him 
and a bunch of other distin- 
guished programmers on a fine 
sunny day at an altitude of about 
3000 feet. Bruce, of course, had 
impeccable taste. He wore an 
olive-drab parachute and used 
structured programming method- 
ology to enter and leave the air- 
plane: One way in, one way out. 

I enjoyed his “How Loosely Are 
You Coupled?” article in the May/ 
June, 1988 issue. It coincides with 
my recent learning about the 
topic, which has been around for 
about ten years. Coupling (and 
the associated topic, “cohesion”) 
will be, I predict, the next pro- 
gramming rage. 

continued on page 10 
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in’de-pen’dent (in’di-pen’dent) 
adj. 1. not influenced by others in opinion, 
conduct, etc. 2. not affiliated; sovereign in 
authority. —7. (in’de-pen-dence) someone 
or something independent. 

FACT: 

Many major dealers specializing in programming 
tools for personal computers are legal affiliates of 
companies who also publish development software. 


FACT: 


Programmer's Connection is not a publisher and is 
not affiliated to any company that has ever been in 
the business of publishing software. 


When you come to Programmer’s Connection, 
you'll find our knowledgeable, non-com- 
misioned salespeople and technical consult- 
ants will give you an unbiased look at the 
products we carry. 


List Ours 
386 products 
386 AMS/386 LINK by Phar Lap Software New 495 389 
386 DEBUGGER by Phar Lap Software New 195 145 
FoxBASE +/286 by Fox Software New 595 399 
Microsoft Windows 386 by Microsoft 195 129 
NDP C-386 by Microway New 595 529 
NDP FORTRAN-386 by Microway New 595 529 
Paradox 386 by Ansa/Bortand New 895 639 
blaise products 
ASYNCH MANAGER Supports Turbo C 175 ©9135 
C TOOLS PLUS/5.0.... 129-99 
Turbo ASYNCH PLUS/4.0 129 99 
Turbo C TOOLS..... : 129 99 
Turbo POWER SCREEN New 129 99 
Turbo POWER TOOLS PLUS/4.0 129 99 
SoftCode 
by Software Bottling 
List $195 Ours $179 


SoftCode is a screen editor and program generator which makes 
use of language templates. You simply design a screen with the 
editor and SoftCode generates the code using templates. You 
can use Software Bottling's prewritten templates in C, BASIC, 
dBASE, and Pascal or write your own. The templates generate 
full data entry routines with file checking, list checking, range 
checking, calculated fields and more 


borland products 


EUREKA Equation Solver 167-115 
Paradox 2.0 by Ansa/Borland 725 $25 
Paradox 386 by Ansa/Borland 895 639 
Paradox Network Pack by Ansa/Borland 995 725 
Quattro: The Professional Spreadsheet 247, «179 
Reflex: The Analyst 150 105 
Sidekick Plus 200 125 
Turbo Basic Compiler. 100 ~=«68 
Turbo Basic Database Toolbox 100 68 
Turbo Basic Editor Toolbox 100 68 
Turbo Basic Telecom Toolbox 100 68 
Turbo C Compiler 100 ~=«68 
Turbo Lightning 100 68 
Turbo Lightning and Lightning Word Wizard 150 105 
Turbo Pascal 100 ~=«68 
Turbo Pascal Database Toolbox 100 ~=—s«68 
Turbo Pascal Developer's Toolkit 395 285 
Turbo Pascal Editor Toolbox 100 68 
Turbo Pascal Gameworks Toolbox 100 ~=«68 
Turbo Pascal Graphix Toolbox 100 68 
Turbo Pascal Numerical Methods Toolbox 


100 68 
Turbo Pascal Tutor .. 70 = 49 
Turbo Prolog Compiler New Version 150 
Turbo Prolog Toolbox 100 ~—(« 68 


DECLARATION sé INDEPENDENCE 


Please join us in our Declaration of Indepen- 
dence. Call Programmer’s Connection today 
and be sure to ask for your FREE subscription 
to the Connection, our 120 page comprehen- 
sive buyer’s guide. It contains descriptions for 
over 750 products by more than 250 manufac- 
turers, and informative articles by leaders in 
the programming industry. 


CALL for Products Not Listed Here 


USA........ 800-336-1166 


.. 800-225-1166 


Ohio & Alaska (Collect) ... 216-494-3781 
UTS FMR ONAN s iscsi cackescaxetecseccrsntscese 216-494-3781 
FAK ca cece sted cesedexvanwotosneusssonaccvepssaas 216-494-5260 
WEREN ecctesccottnt erence 9102406879 


Business Hours: 8:30 AM to 8:00 PM EST Monday through Friday 
Prices, Availability, Terms and Conditions are subject to change 
©Copyright 1988 Programmer's Connection Incorporated 


PROGRAMMER'S CONNECTION 


database management 


Clipper by Nantucket. 695 519 
dBASE III Plus by Ashton-Tate 695 439 
FoxBASE+ by Fox Software 395 249 
FoxBASE +/386 by Fox Software 595 399 
FrontRunner by Ashton-Tate New 195 175 
Genifer by Bytel .......... 395 249 
HI-SCREEN XL by SOFTWAY 149° 129 
Magic PC by Aker ................. 199 179 
R:BASE for DOS by Micronm 725 §39 
microsoft products 
Microsoft C Compiler 5 w/CodeView 450 299 
Microsoft COBOL Compiler w/Tools New Version 900 659 
Microsoft FORTRAN Optimizing Comp 450 299 
Microsoft Macro Assembler... 150 105 
Microsoft Mouse Al Varieties CALL CALL 
Microsoft OS/2 Programmer's Toolkit 350 239 
Microsoft Pascal Compiler 300 199 
Microsoft QuickBASIC 99 «69 
Microsoft QuickC 99 69 
Microsoft Windows 99 69 
Microsoft Windows 386 195 129 
Microsoft Windows Development Kit 500 329 
Microsoft Word 450 299 
Microsoft Works 195 129 
Turbo Programmer 
by ASCII 


List $389 Ours $309 

Turbo Programmer/C 

List $499 Ours $399 
Turbo Programmer is an application development system 
designed to quickly and efficiently produce database applica- 
tions in Turbo Pascal or C. All you do is draw and paint your 
screens and tell Turbo Programmer how you want to retrieve your 
data. With Turbo Programmer you can create entire database 
application programs complete with b-tree indexes, context-sen- 
sitive help, and automatic programmer documentation 


nostradamus products 


Instant Assistant 100 89 
Instant Replay III 150 129 
Turbo-Plus Supports Turbo Pascal 4.0 100 «= 89 
peter norton products 

Advanced Norton Utilities 150 89 
Norton Commander 75 55 
Norton Editor 75 =«459 
Norton Guides Specify Language 100 65 

For OS/2 150 109 
Norton Utilities 100 «= 59 


software bottling products 
Flash-up. 89 79 
Flash-up Developer's Toolbox 4947 


ORDERING INFORMATION 


FREE SHIPPING. Orders within the USA (lower 48 
States only) are shipped FREE via UPS Ground. Call 
for APO, FPO, PAL, and express shipping rates 

NO CREDIT CARD CHARGE. VISA, MasterCard 
and Discover Card are accepted at no extra cost 
Your card is charged when your order is shipped. 
Mail orders please include expiration date and 
authorized signature. 

NO COD OR PO FEE. CODs and Purchase Orders 
are accepted at no extra cost. No personal checks 
are accepted on COD orders. POs with net 30-day 
terms (with initial minimum order of $100) are 
available to qualified US accounts only 

NO SALES TAX. Orders outside of Ohio are not 
charged sales tax. Ohio customers please add 5% 
Ohio tax or provide proof of tax-exemption 
30-DAY GUARANTEE. Most of our products come 
with a 30-day documentation evaluation period or 
a 30-day return guarantee. Please note that some 
manufacturers restrict us from offering guarantees 
on their products. Call for more information. 
SOUND ADVICE. Our knowledgeable technical 
staff can answer technical questions, assist in 
comparing products and send you detailed product 
information tailored to your needs. 
INTERNATIONAL ORDERS. Shipping charges for 
International and Canadian orders are based on 
product weight. The standard rates used are 
published in the Fall 1988 issue of our Buyer's 
Guide. If you do not have a copy, please call or 
write for the exact cost. All payments must be 
made with US funds drawn on a US bank. Please 
include your telephone number when ordering by 
mail. Due to government regulations, we cannot 
ship to all countries. 

MAIL ORDERS. Please include your telephone 
number and complete street address on all mail or- 
ders. Be sure to specify computer, operating sys- 
tem, diskette size, and any applicable compiler or 
hardware interface(s). Send mail orders to: 


Programmer's Connection 
Order Processing Department 
7249 Whipple Ave NW 
North Canton, OH 44720 


Screen Sculptor Supports Turbo Pascal 
SoftCode Supports Bortand Languages... 
Speed Screen 350s 34 


New 


turbo pascal utilities 


Btrieve /SAM File Mgr by Novell 245 184 
Overlay Manager by TurboPower Software 45 43 
TDEBUG 4.0 by TurboPower Software 45 43 
Turbo Analyst by TurboPower Software 75 ~=«69. 
Turbo Professional 4.0 TurboPower 99 = 89 
Turbo Programmer by ASCII. 389 309 
TurboHALO by /MSi, Specify Turbo C or Pascal 95 75 
other products 
Brief by Solution Systems 195 CALL 
CBTREE by Peacock Systems 159 129 
Dan Bricklin's Demo II by Software Garden 195 179 
Epsilon EMACS-type Text Editor by Luganu 195 149 
OPT-Tech Sort by Opt-Tech Data Proc 149° 129 
PolyAwk by Polytron New 99 95 
PolyShell by Polytron 99 «95 
tisC Assembly Language by IMSI 80 65 
Source Print by Powerline Software 97 79 
Tree Diagrammer by Powerline Software 77 65 
Turbo Programmer/C by ASC New 499 399 


Established 1984 


DIALOG 
continued from page 8 


Coupling and cohesion were 
brought out of the closet by E. 
Yourdon and L. Constantine in 
their 1979 Prentice-Hall book, 
Structured Design. A lot of pro- 
grammers are just now talking 
about it in the magazines. There 
is an excellent summary of it in 
PJ. Plauger’s “Programming on 
Purpose” column in the January, 
1988 issue of Computer Language. 
(See also an interesting related let- 
ter to the editor, entitled “The 
Zen of Plauger,” in the April, 1988 
issue.) 

There were a few things I 
wanted to touch on in Webster’s 
article. First, there were two dis- 
turbing points mentioned. Dealing 
with global variables by passing 
them as parameters to a module 
does not reduce coupling. Global 
variables are global variables. No 
matter how you access them, the 
trouble remains the same: You're 
never quite sure how other mod- 
ules affect them, and you’re never 
sure if what you’re doing to them 
adversely affects some other 
module. 

The other point is that the sort 
routine of Listing 3 is not quite 
“completely” decoupled. The com- 
plexity of its interface requires the 
programmer to worry about how 
the routine does its job: It needs 
to know the number of bytes in 
each array element, as well as the 
number of elements. In addition, 
coupling is raised with the implicit 
assumptions that only numbers 
will be sorted, and that numbers 
will be in the array. A completely 
decoupled sort routine procedure 
header would look something like 
this: 

PROCEDURE Sort(VAR AnyStructure); 


I don’t think Pascal can handle 
such a declaration, but from what 
I’ve read, C can do it with func- 
tion pointers. 

Thanks, Bruce, for some 
thought-provoking reading. I’m 
looking forward to the next in- 
stallment. 


—Bill Parker 
Culver City, CA 


I take issue with Bill’s assertion that 
passing global variables as param- 
eters, instead of modifying them di- 
rectly (based on scope), doesn’t reduce 
coupling. One measure of coupling is 
the ability (or lack thereof) to pick up 
a routine from one program and drop 
it into another without modification; 
another is the ability to use the routine 
with various sets of parameters. Direct 
use of globals increases coupling in 
both of those respects. 

As for the sort routine—there’s a 
distinction between coupling and 
generality (though the two are re- 
lated). A sort routine that I can drop 
into any program and use without 
having to add new global definitions 
(constants, types, variables, other rou- 
tines) ts loosely coupled. This doesn’t 
mean that it has to handle all sorting 
situations; I can have a routine that 
sorts only arrays of integers, and it 
can still be loosely coupled if it meets 
the criteria above. 

Bill’s example of a general sort rou- 
tine, though, is possible in Turbo 
Pascal, which does allow untyped 
VAR parameters (all versions) and 
procedural parameters (version 5.0, 
though you can kludge them in earlier 
versions). You would need to pass the 
structure, the size of a given element 
in bytes, the total number of elements 
in the structure, and a pointer to the 
function that compares any two ele- 
ments and returns True if the first ts 
less than the second, False otherwise. 

And yes, it’s true, I did jump out 
of a plane with Bill and the other 
charter members of the PMS Com- 
mando Team (and we won't discuss 
having my right boot momentarily en- 
tangled in my suspension lines after 
the parachute opened). What “Col- 
onel” Bill Parker failed to mention is 
that he’s the one who proposed the 
jump in the first place. We all wore 
custom T-shirts stating that this was 
the “Ist Annual Idiot Programmers’ 
Jump,” which would make Bill... 
naw, it’s too easy. Good to hear from 
you, Colonel. 

—Bruce Webster 


MANDELBROT MANIA 


Let me start off by saying that I 
enjoyed immensely Fred Robin- 
son’s article, “Plotting the Mandel- 
brot Set With the BGI,” in your 
May/June, 1988 issue. I enjoyed 

it not only because I am a Man- 
delbrot Set fan but also because it 


illustrated very well the use of the 
BGI for making a program device 
independent. 

You may not be aware of it, but 
there are a lot of us out there who 
work with the Mandelbrot Set— 
some seriously and others like me 
who do it for fun. As a matter of 
fact, we have our own newsletter 
called Amygdala, which has a cir- 
culation of a few hundred copies 
and comes out about ten times a 
year. 

Amygdala is published by Rollo 
Silver, and costs $15 for ten issues. 
The address is: 


Amygdala 
P.O. Box 219 
San Cristobal, NM 87564 


I look forward to seeing more 
interesting articles in your publi- 
cation. 


—Hector Santos 
Los Angeles, CA 


Fred’s Mandelbrot Set article gener- 
ated an astonishing volume of mail 
and CompuServe activity for some- 
thing most of us here considered a so- 
phisticated party game. Fred has re- 
written and greatly improved his 
Mandelbrot Set generator, and now 
makes it available as a shareware 
product. Those interested may obtain 
it directly from Fred for $15: 


Fred Robinson 
29766 Everett 
Southfield, MI 48076 


Another TURBO TECHNIX au- 
thor, Jon Shemitz, offers a very inno- 
vative Mandelbrot generator that 
plots a “sparse” image—setting only 
every fifth pixel and every fourth scan 
line—very quickly so that you can 
cancel the full plot if the image doesn’t 
look interesting enough at first glance. 
The program, which also features 
mouse-based crosshair zooming, may 
be obtained directly from Jon for $25: 


Jon Shemitz 
Emerald City Software 
1805A Felt Street 
Santa Cruz, CA 95062 
Many thanks to Hector for bring- 
ing Amygdala to the readership’s 


attention. @ 
—Jeff Duntemann 
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Now available in Turbo C,° Microsoft C,” 
JPI Modula 2,” and Logitech Modula 2.” 


Turbo Expert. Now it doesn't 
take a genius to plug into Expert Systems. 


For only $99.95, you can incorporate the power of a full-fledged Expert System into your TURBO PASCAL programs. Seamlessly. Affordably. 
Finally. Actual Expert Systems, developed for simple use by any Turbo Pascal 4.0 programmer. 

Take a look at all the features you suddenly have available with this single Turbo Pascal 4.0 Unit: The ability to create large Expert 
Systems, or even link multiple Expert Systems together. A powerful backward-chaining inference engine. Easy flow of both data and program 
control between Turbo Expert and the other parts of your program, to provide Expert System analysis of any database, spreadsheet, file 
or data structure. The ability to add new rules in the middle of a consultation, so your Expert Systems can learn—really /earn—and 
become even more intelligent. 

You also have the ability to create large rule bases and still have plenty of room left for your program, thanks to conservative memory 
use. You can link multiple rule bases, you'll be compatible with our Turbo Companion units, and you have available advanced features like 
date and time arithmetic, confidence factors, windowing, demons, agendas, blackboards, and more. 

Imagine a single “EXE” file containing your user interface and data handling, and a full Expert System. 

For a limited time, get a FREE copy of our Turbo SnapShot graphics package worth $79.95. We'll give one away with every copy of 
Turbo Expert sold between now and September 30. This package will let you capture graphics images from other programs 
and use them in any Turbo Pascal program. SOFTWARE 


You can even convert images from any CGA or EGA format to any other. 
On top of all that, Turbo Snapshot has routines for graphic gauges and dials as well as mouse support. You'll have all 
you need for a sophisticated graphics front-end for your Expert Systems —free. 


Call for more information or to order, (317) 876-3042. Software Artistry Inc., 3500 Depauw Blvd., Suite 2021, Indianapolis, 
IN 46268. Include $5.00 for shipping and handling. ARTISTRY 


TURBO PASCAL 


TURBO PASCAL 5.0: 


I CAN SEE! 


When your Turbo Pascal program catches a bug, let the 
Borland Integrated Debugger help you with the diagnosis. 


Jeff Duntemann 


My initial reaction to Turbo Pascal 4.0 was 
summarized well in a single word: Wow! 
If I had to characterize my initial reaction 
to release 5.0, it would be a different but 
no less enthusiastic response: I can see! 

The better part of doing what you must 
is seeing what you’re doing, and while you can work 
in the dark, you can work faster with the lights on. 
The whole thrust of 5.0 is to turn the lights on, via 
the Integrated Debugger. 


LET THERE BE LIGHT 


A Pascal program consists of code and data, and 
neither can be observed directly. Instead, you look to 
a program’s effects: what it puts on the screen, what 
it prints to the printer. There are always inferences 
to be drawn, and if you draw the wrong inferences, 
you lose. 

The Integrated Debugger lets you look directly at 
both program execution and program data. The 
means is remarkably straightforward: With a pro- 
gram displayed in the editor window, a colored high- 
light bar (called the execution bar) covers the next 
statement to be executed. You press a function key. 
Bang! That statement executes, and the bar moves to 
the next statement. Press the function key again. 
Bang! The statement executes, and the bar moves yet 
another step forward. 

All the while, in a separate window beneath the 
edit window, one or more variable names appear be- 
side a display of their current values. After each 
statement is executed, the values of the displayed 
variables are rewritten to the screen. Thus, while the 
program runs, you can watch the ebb and flow of 
program data in the window, which is called the 
watch window. 

The synergy between the execution bar and the 
watch window cannot be overemphasized: You can 
now determine exactly when the value of a variable 
changes. Spotting “side effects,” where a stretch of 
code modifies an apparently uninvolved variable, is 
now a snap. Place the corrupted variable in the 


SQUARE ONE 
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watch window, and then step through the code until 
the variable changes. What took hours to solve by in- 
ference now takes seconds—simply because you 

can see. 


INTEGRATED INSTRUMENTS 


The Integrated Debugger’s tools fall into two 
categories: 


® Tools that control program execution; and 
® Tools that manage the display of data items. 


Let’s look at execution control first. 

The Integrated Debugger offers the choice of two 
methods to control program execution: single- 
stepping and breakpoints. A breakpoint is a stop sign 
that can be erected anywhere in the source code file. 
Once the breakpoint is set, simply run the program. 
When execution reaches the breakpoint, the pro- 
gram pauses, but nothing is lost: The state of the pro- 
gram is retained, and the program can be started 
again as though it had never stopped. 

Single-stepping is just that: The program executes 
one line of code, and then pauses. As with break- 
points, the pause is not destructive. Single-stepping 
your way through a program is logically equivalent 
to simply running the program without interruption. 

This is a good place to make an important distinc- 
tion: The Integrated Debugger is a line-oriented sys- 
tem. The execution bar highlights an entire line of 
source code, not a single Pascal statement. If a line 
contains more than one statement, all of the state- 
ments on that line are executed in one single step. 

Of course, much of the power of Pascal stems 
from its procedural nature, in which a number of 
statements are grouped together as a named proce- 
dure that’s invoked as a single statement. Do you 
execute the whole procedure as though it were a sin- 
gle statement? Or do you enter the procedure and 
then execute its component statements individually? 

You do what you must. Turbo Pascal 5.0 lets you 
have it either way. Two separate commands control 
single-stepping: Step over (F8) and Trace into (F7). 


Step over treats a subprogram as an 
indivisible statement, executing it 
completely before pausing again. 
Trace into enters the subprogram 
and allows you to single-step the 
subprogram’s statements as well. 
The two commands are inter- 
changeable (except for their ef- 
fects). You can merrily step along 
the main program, treating sub- 
programs as statements, until you 
reach a subprogram call that’s 
been acting suspiciously. Then 
you can duck into the call and 
take a close look around. 
Breakpoints and single-stepping 
work very well together. In a 
larger program, you may have a 
strong hunch where a problem 
lies. Instead of tediously single- 


stepping to that point, set a break- 
point shortly before the point 
where you expect the trouble be- 
gins, and then execute the pro- 
gram without pausing until that 
breakpoint is reached. From the 
breakpoint, carefully single-step 
until trouble happens. 


LOOKING FOR TROUBLE 


Trouble, when you see it, may be 
a bad branch or some other fail- 
ure of program control. More 
likely, trouble will mean that a 
variable is filled with the right 
stuff at the wrong time, or the 
wrong stuff at the right time, or 
the wrong stuff all the time. To 
spot that kind of trouble, variables 
as well as program code must be 
watched. The Integrated Debug- 
ger offers two mechanisms for 


this process: the watch window 
and the evaluation box. Both are 
ways of looking at the contents of 
program variables. The watch win- 
dow allows you to watch a variable 
continuously while the program 
runs. The evaluation box lets you 
take a quick peek at something at 
irregular intervals, and also lets 
you change the values of program 
variables when program execution 
is paused. 

The 5.0 watch window takes the 
place of the Turbo Pascal 4.0 out- 
put window on the screen when- 
ever debugging is enabled. One 
or more variables can be placed 
into the watch window, and the 
display of their values is updated 


continued on page 14 
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in the window every time program 
execution pauses for a breakpoint 
or after a single-step. 

Unlike the watch window, 
which always displays during de- 
bugging, the evaluation box ap- 
pears only when summoned. 
When the name of a variable is 
typed into the box, the variable’s 
current value appears below its 
name. Alternatively, you can 
“point and shoot” by placing the 
cursor on a variable name and 
pressing Ctrl-F4; the variable 
name appears in the evaluation 
box automatically. Whole expres- 
sions may be “grabbed” from the 
edit buffer by placing the cursor 
at the start of an expression and 
then using the right arrow key to 
copy as much text as desired into 
the box. A new value for the vari- 
able can also be entered; this 
value is then loaded into the vari- 
able, ready for use when program 
execution restarts. 

Both the watch window and the 
evaluation box can display data in 
many different ways. Binary val- 
ues may be displayed as sequenc- 
es of bytes in decimal or hex. Rec- 
ords may be displayed with field 
labels or without. Pointers appear 
as pairs of segment and offset 
values. Dynamic variables are dis- 
played as dereferenced pointers. 
Sets are shown as set elements be- 
tween set constructor brackets, 
with closed intervals identified 
and displayed as such. Files, when 
displayed, indicate their current 
mode (OPEN, CLOSED, READ, or 
WRITE) and the physical file- 
name to which they have been as- 
signed. Arrays are displayed in the 
same format that array constants 
are defined. 

Furthermore, data may be dis- 
played in terms of simple vari- 
ables and expressions. The ex- 
pression may include literals, 
constants, variables, all legal 
Turbo Pascal operators, typecasts, 
and a limited suite of standard 
functions that include SizeOf, Abs, 
Chr, Ord, Succ, Pred, Length, 
Addr, CSeg, DSeg, Seg, Ofs, Ptr, 
SPtr, SSeg, I[OResult, MemAvail, 
MaxAvail, Hi, Lo, and Swap. 

Examples of various ways to dis- 
play data in a watch window are 
shown in Figure 1. 


DISPLAY SWAPPING 

The process of watching code in 
the edit window, and watching 
variables in the watch window, 
doesn’t leave any room on the 
screen for the operation of the 
program being examined. Given 
that most modern programs use 
the entire screen, it seemed inap- 
propriate to divide the screen yet 
another time for a run window. 
Instead, Turbo Pascal 5.0 uses a 
system called display swapping to 
share the screen between the two 
debugging windows and the appli- 
cation being debugged. 

During the debugging process, 
the Integrated Debugger ordinar- 
ily keeps control of the visible 
screen. A screen buffer for the ap- 
plication being debugged is main- 
tained in memory. This buffer is 
brought into view only when the 
application needs to write to the 
screen, and then only long 
enough for the write operation to 
take place. Then the altered 
screen is saved back out to mem- 
ory, and the Integrated Debugger 
takes control of the screen again. 
These steps happen very quickly, 
especially on fast 286 or 386 
machines. 

This feature, called smart display 
swapping, is the default mode. You 
can also specify that the applica- 
tion take over the display every 
time the application executes a 
statement, or that the application 
and the Debugger share the same 
screen. (This works acceptably 
well if the application does little 
or no screen I/O. If the Debugger 
screen is disrupted, the screen can 
be rewritten by a menu com- 
mand.) Turbo Pascal 5.0 can also 
circumvent the display problem by 
allowing dual-screen operation, 
with the Debugger on the mono- 
chrome screen and the applica- 
tion on the color screen. 


GOIN’ ON A BUG HUNT 


Neil Rubenking was nice enough 
to share a bug he tangled with 
while developing his directory 
search engine (See “A Directory 
Search Engine in Turbo Pascal,” 
p. 27 of this issue.) The bug would 
rear its ugly head during any use 
of the search engine, but let’s 
track it down in the context of the 
Where program presented in 
Neil’s article. 
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The bug came to light while 
testing WHERE.EXE in a directory 
that contained a number of files 
whose names included the string 
“ENGINE”: ENGINE.PAS, EN- 
GINE2.PAS, and ENGINE3.PAS, 
plus .BAK and .TPU versions of 
the aforementioned files. When 
WHERE was invoked as WHERE 
E*.*, all of the engine files were 
correctly found and displayed. 
However, when WHERE was in- 
voked as WHERE ENGINE*.*, 
none of the files turned up. 
Hmmmm. 

The flawed copy of EN- 
GINE.PAS is shown in Listing 1. 
(The source code for WHERE.PAS 
is the same as that given in Listing 
3 of Neil’s article.) You can down- 
load the buggy ENGINE.PAS from 
CompuServe if you want to follow 
along in real time—just don’t mix 
up the buggy version with the 
working version from Neil’s 
article! 

Prepare the application for de- 
bugging by loading WHERE.PAS 
into the editor, and entering a 
command line string of “EN- 
GINE*.*” through Options/Pa- 
rameters. Be sure the source code 
for ENGINE.PAS is available to 
the Integrated Debugger. 

Now, we can look at anything 
we want to. So what do we look at? 
A hacker’s hunch tells us that the 
file spec must be getting stepped 
on under certain circumstances, 
so a good place to start is to watch 
the file spec as it wends its way 
through program logic. Since 
Where passes the file spec to 
SearchEngine in a variable called 
template, let’s take the first step of 
setting a watch on template 
through either Break/watch/Add 
watch or its shortcut, Ctrl-F7. To 
avoid having to single-step 
through the procedure that vali- 
dates the command-line param- 
eters, let’s set a breakpoint on 
Where’s invocation of SearchEn- 
gine. To do so, move the cursor to 
the line that contains the call to 
SearchEngine, and toggle a break- 
point on by way of either Break/ 
watch/Toggle breakpoint or its 
shortcut, Ctrl-F8. The line changes 
color. It’s ready. 

Run the program by bringing 
down the Run menu and choos- 
ing the Run option. (In Turbo 
Pascal 5.0, Run is a menu, and all 
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It doesn't matter which language you pro- 
gram in. With Saywhat, you can build beautiful 
elaborate, colorful screens in 
minutes! That's right. Truly 
fantastic screens for menus, 
data entry, data display, and 
help-panels that can all be displayed 
with as little as one line of code in any 
language. Batch files, too. 

With Saywhat, what you see is 
exactly what you get. And response time 
is snappy and crisp, the way you like it. 
That means screens pop up instantly, 
whenever and wherever you want them. 

Whether you're a novice program- 
mer longing for simplicity, or aseasoned 
professional searching for higher produc- 
tivity, you owe it to yourself to check out 
Saywhat. For starters, it will let you build 
your own elegant, moving-bar menus into \ a > 
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prehensive manual included. Not copy protected. No 
licensing fee, fully guaranteed). $49.95 
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If you aren’t completely 
delighted with Saywhat or 
Topaz, return them within 
30 days for a prompt, 
friendly refund. 
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hensive toolkit of dBASE-like commands 
and functions, designed to help you 
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fast. Think of it. With Topaz you can write 
Pascal code using SAYs and GETs, 
PICTURE and RANGE clauses, then SELECT and USE 


—) databases (real dBASE databases!), SKIP through 


records, APPEND data, and lots more. 
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maintain a dBASE file with full-screen editing. Plus 
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licensing fee, fully guaranteed). $49.95 
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Unindent 


Unindent C:WHEREB.PAS 


SearchEngineAll(path, template, Archive, ShowFile, ErrCode): 


TURBO PASCAL 5.0 
continued from page 14 


of Run’s options support debug- 
ging in various ways. The Run op- 
tion is the normal way to run a 
program under the Integrated En- 
vironment, whether you're debug- 
ging or not.) 

Execution pauses at the break- 
point. The watch window shows 
the current value of template: EN- 
GINE*.* (see Figure 2). So far, so 
good—or, so far, no bug. 

The light blue bar on the call to 
SearchEngineAll is the execution 
bar, which rests on the next state- 


ment to be executed, not the state- 
ment that was just executed. At 
this point, we can either execute 
SearchEngineAll as a single state- 
ment by pressing Step over (F8) or 
else descend into SearchEngineAll 
and single-step SearchEngineAll’s 
statements by pressing Trace into 
(F7). Since the problem obviously 
isn’t located in the main body of 
Where, press F7 to duck into 
SearchEngineAll and have a look 
around. 

Nothing changes in the watch 
window. A quick look at the body 
of SearchEngineAll suggests that 
this routine is largely a frame for 
calling SearchEngine. In any 
event, nothing is done to the file 
spec within the body of Search- 


Figure 1. Watches on data items and 
expressions. Note the type casting of 
Byte field Z of a PointRec3D record 
onto a character value. 


Figure 2. The execution bar pauses at 
the breakpoint line. The contents of 
template, as seen in the watch win- 
dow, are still intact. 


EngineAll, which suggests that the 
problem lies somewhere within 
SearchEngine. Before single- 
stepping, move up the source code 
and set a breakpoint at the first 
executable statement in the body 
of SearchEngine by moving the 
cursor to that statement and press- 
ing Ctrl-F8. Once the new break- 
point is set, press Ctrl-F9 to start 
things running again. 

The execution bar moves in- 
stantly to the first line of Search- 
Engine. template hasn’t changed 
... but whoa, hold on: As an ac- 
tual parameter passed by value to 
SearchEngine, template isn’t 


continued on page 22 
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by Stephen Cobb 
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$22.95 600pp. 
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Reference 

by Yvonne McCoy 
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command, and function. 
$24.95 666pp. 
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Reference 

by Stephen Cobb 
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features at your fingertips. 
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new 4GL ol DATABOSS DESIGNS. Databoss is revolutionary because it lets you design and paint data entry 

to develo screens and datafile layouts, as well as menus and reports: DATABOSS then automatically generates the 
velop solid, structured Pascal or C source code that makes up your finished system. 

sophisticated DATABOSS GENERATES. Databoss is a program generator that takes program definitions and produces 

relational database = TURBO Cor TURBO PASCAL 4.0 source code. The definitions are created by pulldown-menu driven 


applications. input screens. Code is generated for menus, file and record editing, file re-index and recovery, reports, 
and file reconfiguration. No coding is necessary for most purposes. 

DATABOSS IS UNIQUE. This unique Skeleton File system allows programmers to change the way 
DATABOSS generates code. This means that DAIABOSS can be used for any application, no matter 
how complex or unusual. 
DATABOSS can be modified to suit the individual programmer's style and requirements. 
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YOU CAN’T BEAT THE FRIENDLINESS. 


DATABOSS IS IDEAL for beginner programmers as It lets them create professional-level Database 
systems with little or no programming required. It also allows beginners to learn Pascal and C more 
quickly and easily for professional applications. 


YOU CAN’T BEAT THE SPEED. 


DATABOSS |S FAST. Professional programmers will find that DATABOSS increases productivity by letting 
them concentrate on the more challenging aspects of their project. DAIABOSS will quickly generate 
thousands of lines of complex, bug-free and easily modified source code that would take even 
professional programmers months of work. 


YOU CAN’T BEAT THE PRICE. 


DATABOSS is a true 4GL, providing more power to the user than dBASE or similar products. 

Itis packaged specifically for ease of design and use. Which would you choose... 

dBASE (database management) + Genifer (code generator) + Clipper (compiler) + R&R (relational 
report writer) = $1,500 PLUS. 

OR 

DATABOSS + Turbo Pascal V4.0 or Turbo C = LESS THAN $500. 


DATABOSS TOOLS 


A function library to enhance the power of DATABOSS. An ideal two-in-one 
Database Toolbox package for users of Turbo Pascal and Turbo C. An 
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DATABOSS COMPONENTS INCLUDE THE FOLLOWING: 


MENU GENERATOR: 


= Unlimited menu nesting 

® Call internal DOS commands 
and external .EXE .COM and 
BAT files with parameters 

® |nclude your own initialization 
and exit routines 

® Display date and time, copyright 
notice and menu heading 

™ Nine security levels and 
modifiable password file 
with user 


SCREEN PAINTER: 


= Free form full screen editor 

™ Draw lines and boxes — 
full IBM extended character 
set displayed choice 

™ Copy, move, insert, center 
text etc. 

® Color painting, foreground, 
intensity and background 
colors 


DATAFILE AND 
FIELD DEFINITION: 


™ Each field defined via a 
4GL template 

™ Up to 16 related datafiles per 
application module 

™ 16 index keys per datafile 
unique or duplicate 

® Up to 9 segments per index key 

® Allows multiple use of fields in 
key segments 

™ Automatic datafile linking 

= Dynamic traceback of linked 
datafiles 

® Unlimited number of open files 

™ Character input control via 
pictures 

® Any field default value allowed 

= Full field validation via 
BOOLEAN check either 
expression or function 

= User defined error messages 

™ Compute and key expressions 

= Automatically generated 
re-indexing module 

® Automatically generated datafile 
reconfiguration module 


THE MOST POWERFUL 
RELATIONAL REPORT 
GENERATOR EVER 
DEVISED 


® Design any type of report 
® Automatic structure definition 
for relational reports 


® A report element can be a field, 


text, function 

® Unlimited number of totals and 
subtotals 

™ Send report elements to CON, 
LST, RS232, DSK individually 
or simultaneously 

@ Paint and build report range 
selection screens to select 
specific data 

@ Print multiple records across 
apage 


IMPEX QUERY BY 
EXAMPLE MODULE 


® |mport external ASCII files into 
your DATABOSS database 
definitions 

™ Query datafiles using point 
and select cursor movements 

™ Select fields to be output 
and specify order 

= |mpose conditions for data 


® Select existing index or create 
on the fly 
® Output to screen, disk or printer 


PROGRAMMERS CAN 
CUSTOMIZE AND MAKE 
APPLICATIONS 

MORE POWERFUL 


= Write your own functions, 
initialization and exit routines 
and include them in the 
function table 

™ Customize a skeleton file and 
use this file at generation time 
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™ Generate 1000 lines of code 
in 10 seconds 

= Compile to produce fast 
executable object code 

® No runtime licence fees 
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screen and printer installation 
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™ Provide the IMPEX query and 
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Falling as they do in the 
shadow of Integrated Debug- 
ging, Turbo Pascal 5.0’s other 
enhancements run the danger 
of being overlooked. This 
would be a mistake—5.0 would 
be a major upgrade even with- 
out its debugging power. 
Perhaps most important— 
overlays are back. Bruce Web- 
ster covers the new unit-based 
overlay system on page 38; it’s 
much smarter and faster than 


especially if EMS memory is 
present in your system. 

EMS support has another 
wrinkle: The editor buffer is 
now placed in EMS memory if 
EMS memory is detected at 
runtime. This step frees up to 


tegrated Environment and for 
your application. 
Apart from overlays, units 


ting them to have private USES 
statements in their IMPLE- 
MENTATION sections, thus 
allowing circular references 
among units to be resolved 
cleanly. The DOS unit contains 
new routines for parsing and 
reading the DOS environment, 
for reading and changing the 
state of the DOS verify flag, 
and for reading and changing 


in DOS. ParamStr(0) returns 
the DOS Exec path. 

Neil Rubenking explores an- 
other 5.0 enhancement, proce- 
dural types, in “A Directory 


on page 27 of this issue. 

Turbo Pascal 5.0 now aligns 
data items in the data segment 
and on the stack on machine 
word boundaries. (The heap is 
not affected.) This allows the 
CPU to fetch data from mem- 
ory as much as 20 percent fas- 
ter than before. A new com- 
piler directive, {$A+}, has been 


THE EVOLUTION OF A SYSTEMS 


the scheme in Turbo Pascal 3.0, 


64K of DOS memory for the In- 


have been enhanced by permit- 


the state of Ctrl-Break checking 


Search Engine in Turbo Pascal” 


provided to enable or disable 
this feature, which may affect 
assembly language routines 
that make assumptions about 
data offsets from BP in the sub- 
program stack frame. 


FLOATING POINT 
EMULATION 


4.0 supported several IEEE nu- 
meric types: Single, Double, Ex- 
tended, and Comp. However, 
these types were supported only 
on machines that contain an 
87-family numeric coprocessor. 
Turbo Pascal 5.0 now emulates 
the math coprocessor when it’s 
run on machines that don’t 
have a math coprocessor, by us- 
ing the same system described 
by Roger Schlafly in “Floating 
Point in Turbo C,” TURBO 
TECHNIX, January/February, 
1988. In brief, when an .EXE 
file generated by Turbo Pascal 
5.0 is run, the file tests for the 
presence of an 87, and then 
either uses the coprocessor di- 
rectly (for the fastest possible 
floating point support), or else 
emulates the coprocessor at the 
cost of some performance. 


CONSTANT EXPRESSIONS 


In all previous versions of 
Turbo Pascal, a named constant 
could be defined only by equat- 
ing it to some literal value. De- 
fining a constant in terms of 
expressions that incorporate 
arithmetic operators and pre- 
viously defined constants is 
standard procedure in many 
languages, including assembler 
and C. Turbo Pascal 5.0 now al- 
lows constant expressions that 
contain previously defined con- 
stants, most arithmetical, logi- 
cal, bitwise and set operators, 
and a limited number of stan- 


dard functions including Size- 
Of, Length, Abs, Chr, Ord, 
Succ, Pred, Length, Hi, Lo, and 
Swap. 

The most important use of 
constant expressions is to 
create a “ripple down” effect 
that changes the values of 
many constants, based upon a 
single constant defined earlier 
in the program. A good exam- 
ple involves the many “magic 
numbers” sent out to UART 
control registers in telecom- 
munications applications. 
These numbers differ depend- 
ing upon which serial port is to 
be used. A set of constant ex- 
pressions based upon a port 
number allows the source code 
to be altered for a new serial 
port simply by changing a 
single constant definition: 


COMPORT = 1; {1=COM1: 2=COM2:} 
COMBASE = $2F8; 
PORTBASE = COMBASE OR 
(COMPORT SHL 8); 
THR = PORTBASE; 
RBR = PORTBASE; 
IER = PORTBASE + 1; 
IIR = PORTBASE + 2; 
LCR = PORTBASE + 3; 


Here, all you have to do to 
change to serial port COM2 is 
redefine the constant COM- 
PORT to 2, and the change 
propagates through the rest of 
the constants automatically. 


BGI ENHANCEMENTS 


The Borland Graphics Inter- 
face has been considerably en- 
hanced for Turbo Pascal 5.0 
with the addition of several 
new drivers and many new pro- 
cedures and predefined con- 
stants. The IBM 8514 is now 
supported in its 640 X 480 and 
1024 X 768 modes, and the 
VGA driver suite includes sup- 
port for the 320 X 200 X 256 
color mode. The 8514 is fully 
supported by all BGI features 
(except that FloodFill does not 
work on 8514 graphics). Also, 

a new routine, SetRGBPalette, 
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performs palette management 
for all 256-color modes on the 
8514 and the VGA; the earlier 
BGI palette routines don’t work 
in 256-color mode. Another 
procedure, SetRGBColor, per- 
forms color management for 
256-color modes. 

A Sector procedure has been 
added to draw elliptical or cir- 
cular segments that may be 
filled using the scan converter. 
A separate new routine, Fill- 
Ellipse, draws full ellipses that 
are automatically filled with the 
current fill color and fill style. 

New mechanisms enable the 
registration of BGI fonts and 
drivers provided by non- 
Borland sources. InstallUser- 
Driver installs a third-party 
graphics driver into the BGI 
driver table. InstallUserFont 
performs the same function for 
third-party fonts. Other new 
BGI procedures and functions 
include GetMaxMode, which 
returns the maximum mode 
number for the loaded driver; 
GetModeName, which returns 
the name of a mode given its 
number; SetAspectRatio, which 
allows fine-tuning of X/Y ratios 
to correct for misaligned dis- 
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play screens; SetWriteMode, 
which specifies the binary op- 
eration (XOR or MOV) used in 
drawing straight lines; and Set- 
UserCharSize, which allows the 
width and height of stroked 
fonts to be varied. 

New predefined constants in- 
clude CurrentDriver, for calls 
that require a driver ID num- 
ber. 


TURBO DEBUGGER 
SUPPORT 
Turbo Pascal 5.0 fully supports 
Turbo Debugger for standalone 
symbolic debugging. In con- 
trast to 5.0’s Integrated De- 
bugger, Turbo Debugger lets 
you follow the effects of your 
program through all levels of 
the underlying system includ- 
ing memory, stack, and ma- 
chine registers. All of the fea- 
tures described by Michael 
Abrash in “Turbo Debugger: 
The View From Within” (p. 52 
of this issue) may be used with 
Turbo Pascal 5.0 just as easily 
as with Turbo C 2.0. 

Figure 1 shows a Turbo De- 


Figure 1. Turbo Debugger as it 
might appear while tracing a 
Turbo Pascal 5.0 program. The 
assembly language equivalents of 
two Turbo Pascal statements are 
shown in the CPU viewer window. 


bugger screen as it might ap- 
pear while single-stepping a 
small program. The source 
code file is displayed in a mod- 
ule viewer window, while the 
generated machine code for 
each Turbo Pascal statement is 
shown with associated assembly 
language mnemonics in the 
CPU viewer window. The state 
of all machine registers and 
flags is updated after each 
statement is executed. A vari- 
able viewer window contains all 
variables visible in the current 
scope; any of these variables 
may be chosen for closer 
examination. 


ALL SYSTEMS GO 

With every new release since 
1983, Turbo Pascal has moved 
more and more toward a true 
systems-implementation lan- 
guage. I now consider it to be 
the functional equivalent of 
C—no part of the PC system is 
beyond its grasp. Turbo Pascal 
still puts the much-maligned 
safety railing between you and 
the cliff edge, but if you really 
want to walk over that cliff, it’ll 
gently help you past the rail- 
ing—and then say... g’day. @ 
— Jeff Duntemann 
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ompile 


VAR 
$ : SearchRec; 
P : PathStr; 
Ext : ExtStr; 


BEGIN 


*C:Neng inex. 


Mask ‘= Mask + Ext;} -——— 
FindFirst(P + Mask, 
IF DosError <> 6 TH 

BEGIN 


ErrorCode ‘= DosError; 


WHILE DosError 
BEGIN 
Proc(S, P); 
FindNext (S$); 


8 DO 


ile dit ompile 


Line 69 Insert 


VAR ErrarCais : 


VAR 
§ : SearchRec; 
P : PathStr; 
Ext : ExtStr; 


pt ions 
Edit 


reak/watch 


Ctrl-F4 


Evaluate 


Debug reak/watch 
| Evaluate Ctrl-F4 
Byte)| Call stack Ctrl-F3 
ind function 
| Integrated debugging On’ 
fall -} t 


SEARCHENGINE( C:Nengine®.’ ,32,PTR(S784B, $ 


SEARCHENGINEALL(’C:\’ ,’ engine*.*’ ,32,PTR( 


BEGIN 


Mask := Mask + Ext; 
FindFirst(P + Mask, Attr, S$); 
IF DosError <> 8 THEN 
BEGIN 
ErrorCode ‘= 
Exit; 
END; 
WHILE DosError 
BEGIN 
Proc(S, P); 


DosError; 


6 DO 


-Scroll View call 


TURBO PASCAL 5.0 


continued from page 16 


referenced from within Search- 
Engine. A watch was set—but on 
the wrong item. There’s a lesson 
here: Keep things like scoping in 
mind while you debug, especially 
while you’re learning the Inte- 
grated Debugger, and doubly es- 
pecially if you’re just learning to 
program. 

At this level in the program, the 
file spec is held in a variable 
named Mask. A watch could be set 
on Mask, but the horse could al- 
ready be out of the barn. 


| WHERE 


One way to check is to bring up 
the evaluation box and look at the 
current value of Mask. Place the 
cursor on Mask, press Ctrl-F4, and 
Enter. The evaluation box appears 
with Mask in the Evaluate field, 
and the current contents of Mask 
appear in the box’s Result field 
(see Figure 3). 

Aha! Look closely at the file 
spec: “C:\ENGINE*.”. The second 
asterisk is gone. As a result, DOS 
thinks that this file spec requires 
files that don’t have any file exten- 
sion at all. Nothing in the direc- 
tory matches this file spec. 

Don’t get too excited just yet. 
This is the bug’s spoor; the bug it- 
self is still nowhere in sight. But 


Figure 3. The evaluation box reveals 
a corrupted file spec in variable 
Mask. The final asterisk has somehow 
disappeared. 


Figure 4. Display of the call stack 
shows that the file spec is corrupted 
some time after it’s passed to 
SearchEngineAll, but before it’s 
passed to SearchEngine. 


where to look now? Sadly, execu- 
tion can’t be “backed up” a step at 
a time the way it can move for- 
ward. The wise thing to do here 

is to reset the program to its initial 
state by selecting the Run/Pro- 
gram reset item, and then start 
again. This time, set a watch on 
the right item and begin to single- 
step a little earlier. 

Before we do so, however, let’s 
use another feature of the Inte- 
grated Debugger, and take a quick 
look at the call stack. Select De- 
bug/Call stack, or use its shortcut, 
Ctrl-F3. A box appears that con- 
tains a summary of the current 
state of subprogram nesting, in- 


continued on page 26 
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system for creating: 
Demonstrations - Tut 

When active, Instant Reg s 
that runs, memorizes, and replays programs. 
It has the unusual ability to insert prompts, 
pop-up windows, prot ;, user involve- 
ment, music, and branching menus into 
replays. a 

Building a Demo or Tutorial is easy. Just run 
any program vor Instant Replay” and insert 


explanation -up windows, prompts, user 
involvement, music and so on. Instant Replay” 
remembers everything; it builds a demo that 
will re-run the actual program or a screens 
only prototype version. 

Instant Replay” includes a Screen Maker 
for building pop-up windows, prototype win- 
dows, and menu windows. Other useful tools 
include a Prototyper, Keystroke Editor, Music 
Maker, Menu Maker, Presentation Text Editor, 
Control Guide, and Insertion Guide. 

The screen editor Screen Genie” is de- 
signed to be memorized by /nstant Replay.” 
Creating animations is easy and fun; just run 
Screen Genie” and memorize your activity. 

Instant Replay for |BM and True Compat- 
ibles, requires DOS 2.0 or greater. Instant 
Replay” is not copy protected. There are no 
royalties required for distribution of 
Demos. 


Instant Replay” at $149.95 is an exciting 
new product. Because of the quality of this 
product, Nostradamus" provides a 60-day 
satisfaction money back guarantee. Call or 
write, we accept VISA, AmEx, C.O.D., Check 
or P.O. with orders. Demo diskettes and free 
product brochure available. 

Nostradamus, Inc. 3191 S. Valley Street, 
(ste. 252) Salt Lake City, Utah 84109 
voice (801) 487-9662 

Data/BBS 801-487-9715 1200/2400,n,8,1 


Version ITT 


sic Maker 
Text Editor 
Online Help 
Screen Painter 

Magic Demo Animator 
Dynamic Menu Maker 
Memorize and Replay actual programs 
Memorize and Replay screens only 
Insert: prompts, pop-ups, prototypes, 
music, and user involvement into replays 
Make insertions while creating or 
reviewing 

Generate Vapor Ware from actual 
programs 

Resident Screen Painter for creating and 
grabbing windows on the fly 


Prototyper that includes slide shows, 
menus, and nesting 


Keystroke/time editor, inserter, and 
merger 


Replay chaining and linking 
Modular demo making facilities 
Fast forward and single step modes 
Self Made Tutorial included 

Timed Keyboard Macros 

Numerous and powerful operator input 
options for Tutorials 

Text File Presentation facility 
Transparent Windows 

Change Defaults 

Foreground or Background Music 
Canned special sound effects 
Unlimited replay branching 
Compressed screens 

Object oriented programming 
Tracking editor 

Plus much more .. . 


“Instant Replay™ is one of those 
products with the potential to go from 
unknown to indispensable in your 
software library.” PC Magazine 


“Incredible . .. We built our entire 
Comdex Presentation with Instant 
Replay.” Panasonic 


“Instant Replay™ 
brings new flexibility to prototypes, 
. tutorials, & their eventual implemen- 


tation.” Electronic Design 


a “1 highly recommend Instant Replay.”” 


uter Language 


“You need Instant Replay™!” 
ishington Post 


Instant Replay” > 
Instant Assistant™ ~~~ 
Screen Genie™ 

Word Genie™ 

NoBlink Accelerator™ 
Assembler Genie™ 

DOS Assistant™ 


Programming Libraries 
Supports Turbo Pascal 4.0 


HardRunner™ 
... and more 


Nastraaanitrs 


LISTING 1: ENGINEB.PAS 


UNIT Engine; 
{$v-} 


(II III III IA III I IAT IT IASI ASIII ASIII SAAS ASS ASISISAS: 


SEARCH ENGINE 
Input Parameters: 
Mask : The file specification to search for 
May contain wildcards 
Attr : File attribute to search for 
Proc : Procedure to process each found file 


Ouput Parameters: 
ErrorCode : Contains the final error code. 


(RI IOI III I IAA IAA IAAI AI IAAI AAAS IAAISSSSSSSSSE'S: 


( Gehhehalehehalaiehehaielalelaiaiabeiaiaiated 


(**) INTERFACE (**) 
(ARRRRARAERRRRNENRREEED) 


USES DOS; 
TYPE ProcType = PROCEDURE (VAR S : SearchRec; P : PathStr); 


PROCEDURE SearchEngine(Mask : PathStr; 
Attr : Byte; 
Proc : ProcType; 
VAR ErrorCode : Byte); 


FUNCTION GoodDirectory(S : SearchRec) : Boolean; 
PROCEDURE ShrinkPath(VAR path : PathStr); 
PROCEDURE ErrorMessage(ErrCode : Byte); 
PROCEDURE SearchEngineAll(path : PathStr; 

Mask : NameStr; 

Attr : Byte; 

Proc : ProcType; 

VAR ErrorCode : Byte); 


( Gelahalalalaiaiaiaiehaleiaiehaiaieialeiaiehed } 


(**) IMPLEMENTATION (**) 


( Gelehahahebalahalaiehabeleheiaiaiaiaiaielaled | 


VAR 
EngineMask : NameStr; 
EngineAttr : Byte; 
EngineProc : ProcType; 
EngineCode : Byte; 


PROCEDURE SearchEngine(Mask : PathStr; 
Attr : Byte; 
Proc : ProcType; 
VAR ErrorCode : Byte); 
VAR 
S : SearchRec; 
P : PathStr; 
Ext : ExtStr; 


{procedure FSplit(Path: PathStr; var Dir: DirStr; 
var Name: NameStr; var Ext: ExtStr);) 


BEGIN 
FSplit(Mask, P, Mask, Ext); 
Mask := Mask + Ext; 
FindFirst(P + Mask, Attr, S); 
IF DosError <> 0 THEN 
BEGIN 
ErrorCode := DosError; 
Exit; 
END; 
WHILE DosError = 0 DO 
BEGIN 
Proc(S, P); 
FindNext(S); 
END; 
IF DosError = 18 THEN ErrorCode := 0 
ELSE ErrorCode := DosError; 
END; 


FUNCTION GoodDirectory(S : SearchRec) : Boolean; 
BEGIN 

GoodDirectory := (S.nmame <> '.') AND 

(S.mame <> '..') AND 

(S.Attr AND Directory = Directory); 
END; 


PROCEDURE ShrinkPath(VAR path : PathStr); 
VAR P : Byte; 
Dummy : NameStr; 
BEGIN 
FSplit(path, path, Dummy, Dummy); 
Dec(path (0) ); 
END; 


{$F+} PROCEDURE SearchOneDir(VAR S : SearchRec; P : PathStr); 
{Recursive procedure to search one directory) 
BEGIN 
IF GoodDirectory(S) THEN 
BEGIN 
P := P + S.name; 
SearchEngine(P + '\' + EngineMask, EngineAttr, 
EngineProc, EngineCode); 
SearchEngine(P + '\*.*', Directory OR Archive, 
SearchOneDir, EngineCode); 
END; 
END; 


PROCEDURE SearchEngineAl (path : PathStr; 
Mask : NameStr; 
Attr : Byte; 
Proc : ProcType; 
VAR ErrorCode : Byte); 
BEGIN 
(*Set up Unit global variables for use in 
recursive directory search procedure*) 
EngineMask := Mask; 
EngineProc := Proc; 
EngineAttr := Attr; 
SearchEngine(path + Mask, Attr, Proc, ErrorCode); 
SearchEngine 
(path + '*.*', Directory OR Attr, SearchOneDir, ErrorCode); 
ErrorCode := EngineCode; 
END; 


PROCEDURE ErrorMessage(ErrCode : Byte); 
BEGIN 
CASE ErrCode OF 
; {OK -- no error} 
WriteLn('File not found'); 
WriteLn('Path not found'); 
WriteLn('Access denied'); 
WriteLn('Invalid handle'); 
WriteLn('Not enough memory'); 
: WriteLn('Invalid environment! ); 
: WriteLn('Invalid format'); 
Heise {OK -- merely "no more files") 
ELSE WriteLn('ERROR #', ErrCode); 
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For A 
Code 


If you think writing program code 
is a dirty business, we have something 
to help you clean up your act. 

It’s called Matrix Layout. Layout 
lets you create programs that do 
exactly what you want, quickly and 
easily— without writing a single line 
of code. Layout does it for you auto- 
matically, in your choice of Turbo 
Pascal, Turbo C, Microsoft C, Quick- 
Basic or Lattice C. And if you’re not 
a programmer, you can even create 
programs that are ready-to-run. 

As the first true CASE (Com- 
puter Aided Software Engineering) 
development tool for the PC, Layout 
lets you write your programs simply 
by drawing an icon-based flow chart. 
They'll have windows, icons, menus, 
buttons, dialog boxes, and beautiful 
graphics and text. Like the Macintosh 
and the OS/2 Presentation Manager. 

And because Layout is so effi- 
cient, everything you create will 
work incredibly fast, even on stan- 
dard PC’s with 256K and only one 
disk drive. To top it off, all your pro- 
grams will feature Layout’s auto- 
matic mouse support, sophisticated 
Hypertext functions, and decision 
handling. 

The full Layout package also 


yone Who Considers: 
Four Letter Word. 


comes with three additional programs: 


Matrix Paint is a professional 
paint program that comes with a full 
palette of high-powered graphics 
tools, plus scanner support. And any 
picture or symbol that you draw or 


1. Draw a flow- chart. 
2. Matrix Layout creates 
the program code. 
3. Your program is complete. 


e ~ Matrix eaeware Technology Corporation + One Massachussetts Technology Cente Harborside Drive - Boston, MA 02128 * (617) 567-0037 


~ Matrix Software/UK ¢ Plymouth, England ® 796-363 * Matrix Software/Belgium « Geldenaaksebaan 476 ¢ 3030 Léuven © 016202064 
The following are registered and unregistered trademarks of the companies listed: Matrix Layout, Matrix Paint, Matrix Helpmaker, Matrix Desktop. 


scan into Paint can be included in 
your program. 
Matrix Helpmaker allows you 
to include an electronic manual in all 
your programs. Context-sensitive help 
windows, a table of contents, index- 
ing, and the convenience of Hypertext 
functionality can now become a part 
of everything you create. 
Finally, Matrix Desktop gives 
you the ability to organize your files 
and disks in a very Macintosh-like 
easy to see, easy to use way. # 
Whats the cost? At just $149.95 
for the entire package, Layout speaks 
in a language you'll love to hear. ad 
Especially with our free customer 9” 
support, no copy protection, and a 
30-day, money-back guarantee. 
Video Tape Offer 
Our new demonstration video- 
tape graphically illustrates how the 
many features of Matrix Layout will 
make a difference in your life. Call h 
1-800-533-5644 and order your VHS _ 
copy now (just $9.95 for shipping 
and handling, credited against your 
purchase). In Massachussetts, call 
(617) 567-0037. i P 
Do it today. Because once you # 
see what Layout can do for you, we we 
think eas swear “in it. a 


Matrix Software Technology Corporation: Macintosh, Apple Computer. Inc.; OS/2 Presentation Manager, International Business Machines Corporation. 
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cluding the actual parameters 
passed to each currently active 
subprogram. Examine Figure 4. 

The call stack display shows 
that the program started at Where, 
called SearchEngineAll, and then 
called SearchEngine. But look 
closely at the actual parameters: 
The file spec was passed correctly 
to SearchEngineAll, but was al- 
ready corrupted by the time it was 
passed to SearchEngine. 

We assumed too much when we 
first descended into Search- 
EngineAll. Something in that very 
short and uncomplicated proce- 
dure corrupted the spec. Reset the 
program, reload WHERE.PAS us- 
ing the pick list, and start the pro- 
gram running again. The break- 
points are still there, and 
execution pauses at the call to 
SearchEngineAll. Trace into 
SearchEngineAll with a single 
press of F7, and take a more care- 
ful look around. 

What does the program do to 
Mask between the call to Search- 
EngineAll and the call to Search- 


VISITECH 
SOFTWARE 


Engine? Nothing! The same pa- 
rameter, Mask, is passed through 
untouched. The call stack showed 
that the spec was passed intact 
down into SearchEngineAll. Look 
at Mask again by bringing up the 
evaluation box once more. 


ELEMENTARY, MY DEAR 
PASCAL 
Surprise! Mask is corrupted al- 
ready, to “ENGINE*.”. If we had 
looked at Mask immediately upon 
entering SearchEngineAll, we 
could have avoided the trip on- 
ward into SearchEngine. However, 
we'd still be confronted by a mys- 
tery: The string “ENGINE*.*” is 
passed to SearchEngineAll, and 
the string “ENGINE*.” comes out 
the other side. That’s a subtle 
point, but it should suggest some- 
thing to you. Let’s look at the 
types of the formal and actual pa- 
rameters here. 

The actual parameter, template, 
is type STRING, which is 255 
characters long. However, the for- 
mal parameter to which template 
is passed is type NameStr, which 
is a type defined within the DOS 
unit. If you look in the documen- 


Printed graphics in ultra-high resolution using 
Turbo Pascal 4.0? Introducing... 


GrRAPHLINK™ 


The powerful printer software that gives you the same 
control over your printer that Turbo’s BGI graphics gives 
you over your screen - in ultra-high resolution! 


GrapuHLink commands work exactly like Turbo Pascal’s BGI commands 
wherever possible, so you can quickly add printed graphics to 
your programs. No need to learn a whole new syntax - you 
already know the commands! 


a 


GraPHLink emulates every applicable BGI procedure and function, including 
viewport and image-transfer routines. 


GrapuLink dynamically compresses images in conventional memory, so you 
can store an 8” « 10”, 150 dpi image in as little as 150 kB. 
Optionally uses expanded memory! 


GrapHLinkx supports printers to their highest resolution: 
© HP LaserJet II to 300 dpi e Epson LQ series to 180 dpi 
© NEC and Toshiba 24 pin printers to 360 dpi! 


Only $69 + $5 s/h (PA residents add 6% to total.) 


Requires Turbo Pascal 4.0. Minimum 512 kB of memory recommended 
Satisfaction quaranteed or your money back within 30 days 


D5 3807 Ridgewood Court 
Pittsburgh, PA 15239 
412/733-4775 
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tation for the DOS unit, you'll find 
that NameStr is defined as 
STRING{[8], and therefore is only 
eight characters long. 

The string “ENGINE*.*” is nine 
characters long. Mask literally isn’t 
long enough to hold this string. 
Since strict type-checking for 
strings is disabled through the 
{$V-} compiler directive at the 
start of Where, the final asterisk 
is truncated off into oblivion with 
no one the wiser. 

The bug is that Mask is de- 
clared to be an inappropriate type. 
The solution is fairly simple: De- 
clare a new type in the Engine 
unit that is large enough to hold 
any file spec that doesn’t also in- 
clude a path: 

TYPE 

FullNameStr = STRING[12]; 

Next, redeclare all parameters or 
variables that must contain a file 
spec as type FullNameStr. Now re- 
compile and test it out. 

It works. The bug is dead. Long 
live Turbo Pascal 5.0! 


SIGHT, FORESIGHT, AND 
HINDSIGHT 


Hindsight is always perfect, and 
also perfectly useless. Sure, this 
was an easy bug to spot—but only 
because we had the power to lift the 
hood and take a look. Logical de- 
duction almost never works on 
bugs like this, because we rarely 
remember to think of the match- 
ing of formal and actual param- 
eters as a real program action and 
not simply a formality. Sooner or 
later you'd spot it, but you’d prob- 
ably waste half an hour in the 
process. I’ve wasted far more time 
on far wimpier bugs, simply be- 
cause my mind gets locked into a 
set of assumptions that logic alone 
just won’t crack. 

Debugging is a skill that takes 
some practice to develop. It re- 
quires that you study your chosen 
language and your machine. It re- 
quires that you keep an eye on 
your assumptions, especially the 
deadly one that insists that “noth- 
ing really happens between here 
and there.” Remember that Turbo 
Pascal 5.0 still requires that you 
learn how to look—but now, at 
least, it lets you see. @ 


Listings may be downloaded from 
Library I of CompuServe forum 
BPROGA, as PASBUG.ARC. 


A DIRECTORY SEARCH ENGINE 
IN TURBO PASCAL 


Turbo Pascal 5.0 allows you to build completely 
generalized routines by supporting the passing of procedures— 


and hence program actions—as parameters. 


Neil Rubenking 


Whatever high-level language you use, 
eventually some of your programs will 
need the ability to search a disk directory. 
The machinery to do so is built into DOS, 
and Turbo Pascal 5.0’s DOS unit provides 
= FindFirst and FindNext directory search 
procedures that use DOS’s directory search func- 
tions. To support FindFirst and FindNext, the DOS 
unit provides the SearchRec data type that models 
the DOS disk transfer area (DTA) as a Pascal record. 
Unit DOS also contains built-in constants for each of 
the DOS file attributes. These elements can be com- 
bined into a completely generalized file search “en- 
gine,” placed into a unit, and then used for any pur- 
pose by any program that needs to search a directory 
or a directory tree. 

Engine (Listing 1) is the unit that contains the 
generalized file search engine. Engine contains two 
major procedures, SearchEngine and SearchEngine- 
All. SearchEngine searches a single directory for 
a file that matches a file specification and a file at- 
tribute byte. SearchEngineAll traverses an entire di- 
rectory tree or subtree during its search. Since the 
compiler and the DOS unit handle so much of the 
file search activity, the search engine unit can be 
quite compact. (For information about the theory 
behind DOS directory searching, see “A Directory 
Search Engine in Turbo C” on p. 75 of this issue. In 
this article, I cover the practical implementation of 
DOS directory searches in Turbo Pascal 5.0.) 


WIZARD 


PROCEDURES AS PARAMETERS? 


Procedure SearchEngine takes four parameters. This 
procedure needs to know which file specification to 
seek, which attribute to match, and which procedure 
to call on every found file. SearchEngine then re- 
turns the final DOS error code returned by the DOS 
Find First and Find Next functions. 

If you’re alert, you’re probably wondering how the 
SearchEngine procedure could have a procedure as a 
parameter. Procedural types (and function types) are 
a new feature of Turbo Pascal 5.0. Conceptually, pro- 
cedural types allow you to think of program state- 


ments as just another kind of data. You can pass pro- 
gram actions to a procedure just as easily as you can 
pass an integer or a string to a procedure. This 
makes the creation of certain kinds of general- 
purpose routines possible. These general-purpose 
routines are called “engines” because they provide 
some central service to a wide variety of different ap- 
plications, in the same fashion that a lawnmower en- 
gine can be taken from a lawnmower and used with- 
out modification to power a go-kart. 

A procedure type declaration looks very much like 
a procedure header minus the procedure’s name. 
For example: 


TYPE 


P = Procedure(X : Integer; Ch : Char); 


Procedural type P matches any procedure that has 
parameters of the identical type and order of decla- 
ration. The names of the procedure and its param- 
eters aren’t important, but the types of the parameters 
and their order must match exactly. This is best 
shown by example. Figure 1 contains a number of 
valid and invalid procedure declarations for proce- 
dural type P. Study them closely. 

A variable of some procedural type can be de- 
clared and assigned to a matching procedure, or a 
procedure name can be passed as an actual param- 
eter to another procedure. In either case, the proce- 
dure must follow the far calling convention. Force proce- 
dures to far calling conventions by bracketing their 
procedure headers between {$F+} and {$F-} com- 
piler directives. Don’t forget that step, or your pro- 
gram will crash every time. 

Procedures that may act as procedural variables or 
parameters have other restrictions. These proce- 
dures must be declared at the global level; they may 
not be INLINE or INTERRUPT procedures; and 
they may not be standard procedures that reside in 
SYSTEM.TPU. However, procedures in Turbo Pascal 
standard units, such as DOS and Crt, may act as pro- 
cedural variables and parameters. 

continued on page 28 
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SEARCH ENGINE 
continued from page 27 


Declaration of procedural type P: 


TYPE 
P = Procedure(X : Integer; Ch : Char); 
A valid procedure of type P: 


PROCEDURE Manny(I : Integer; MyChar : 
Invalid procedures for type P: 


Char); 


W is the wrong type: 
PROCEDURE Moe(W : Word; Letter : 
X formal parm not VAR: 
PROCEDURE Jack(VAR I 
Wrong number of parms: 
PROCEDURE Bob(MyGrade : 
Wrong order of parms: 

PROCEDURE Ray(NewCh =: 


Char); 
: Integer; Ch : Char); 
Char); 


Char; K : Integer); 

Figure 1. Valid and invalid procedures for procedural type 
P. Note that the names of the procedures and their param- 
eters do not matter. The type and order of the declaration 
of parameters, and whether a parameter is passed by refer- 
ence (VAR) or by value, are the only things that matter. 


SearchEngine takes the parameter Proc, of type 
ProcType. Each of the example programs contains 
one or more procedures of this type. Within Search- 
Engine, a call to formal parameter Proc has exactly 
the same effect as a call to the procedure passed in 
Proc as the actual parameter. 


THE ENGINE 


ENGINE.PAS (Listing 1) contains the directory 
search unit. SearchEngine uses DOS unit procedures 
FindFirst and FindNext to find all matching files. 
Each time SearchEngine finds a matching file, it calls 
the user-specified procedure passed in procedural 
parameter Proc. Simple! SearchEngine also returns 
the final DOS error code. However, if SearchEngine 
finds at least one file during a search, it doesn’t con- 
sider not finding additional files to be an error. 

Procedure SearchEngineAll searches the given 
path and all of its subdirectories for files that match 
the file specification. Passing a path that specifies a 
volume’s root directory, such as “C:\,” to SearchEn- 
gineAll tells the procedure to search the entire vo- 
lume. SearchEngineAll uses the file specification, at- 
tribute, and user-specified procedure to call Search- 
Engine in order to find and process all matching 
files in a given directory. SearchEngineAll then calls 
SearchEngine a second time. This time, however, 
SearchEngineAll searches for subdirectories by spec- 
ifying the directory attribute bit for the search. 
SearchEngineAll then uses procedure SearchOneDir, 
which is passed as a procedural parameter of type 
Proc, to process the subdirectories that have been 
found. 

Like SearchEngineAll, SearchOneDir makes two 
calls to the regular SearchEngine—one call matches 
files, and the other call searches for more directo- 
ries. Hence, SearchOneDir and SearchEngine form 
a recursive loop. At each level of nesting, SearchOne- 
Dir uses SearchEngine to look for any subdirectories. 
If SearchEngine finds any subdirectories, it calls 
SearchOneDir again. This process continues until all 
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of the subdirectories located beneath the initial path 
passed to SearchEngineAll have been processed. 
(For a discussion of recursion, see “Recursing with- 
out Cursing,” TURBO TECHNIX, July/August, 1988.) 

Other handy routines for directory searches are 
included in ENGINE.PAS. Function GoodDirectory 
returns True only if its SearchRec parameter refers 
to a file that has the directory attribute and is neither 
the current directory nor the parent directory (i.e., 
neither “.” nor “..”). ShrinkPath removes the last sub- 
directory from a path, using Turbo Pascal 5.0’s new 
FSplit procedure. Procedure ErrorMessage then 
prints a message that’s appropriate to the DOS error 
code passed to this procedure. These other routines 
are used in the example programs. 


INSTANT DISK UTILITIES 


The various routines in Engine let you write useful 
DOS disk utilities with very little additional code. Dir- 
Sum (Listing 2) shows just how tiny a program that 
uses the Engine unit can be. Small enough to fit on 
one 25-line screen, DirSum manages both to display 
the names of all of the files in the current directory 
and to tally their sizes into one total size value. How 
can DirSum be so small? Because all of the work 
happens elsewhere. DirSum passes procedure Write- 
It to SearchEngine, which causes the engine to write 
the name of every file that it finds. When DirSum 
has displayed the names of all of the files in the cur- 
rent directory, it then displays the total number of 
bytes of disk space that these files occupy. That’s aw- 
fully easy, though. Let’s give the search engine more 
of a challenge. 

WHERE.PAS (Listing 3) contains Where, a pro- 
gram to find files that match a file specification lo- 
cated anywhere on your disk. With SearchEngineAll, 
a task like this is almost ridiculously simple. Simply 
pass the path, file template, and file attribute to 
SearchEngineAll, along with the procedure for pro- 
cessing each found file. In this case, procedure 
ShowFile displays the full pathname of each found 
file and—as a bonus—updates a tally (as does Dir- 
Sum) of how much disk space the found files occupy. 
ShowFile uses standard output for its screen displays 
(note that the Crt unit is not named in the USES 
statement). A handy disk file of found files can be 
created by redirecting Where’s output to a file. For 
example, the invocation WHERE *.* > AL- 
LFILES.DIR creates a file named ALLFILES.DIR 
that lists the name of every file located anywhere on 
the current volume. 

DELBAK.PAS (Listing 4) contains program Del- 
Bak. DelBak performs a useful housecleaning task— 
it deletes all .BAK files on the current volume. If you 
haven’t purged your .BAK file collection in a while, 
you may find that these files occupy tens or even 
hundreds of thousands of bytes of hard disk space. 

DelBak is similar in structure to Where. Again, 
SearchEngineAll does all of the work. The file spec- 
ification is fixed as “*.BAK.” The action procedure 
passed to SearchEngineAll is DelFile, which simply 
deletes the found file and notes how many bytes 
were saved. 


story continues on page 36 
listing begins on page 34 


The 


revolution 
continues... 


What started 
modestly 
enough in 
November of 
1983 with the 
launch of our 
first program, 
Turbo Pascal®, became a revo- 
lution and it has been going like 
a rocket ever since. 


We've changed the way you 
program. We invented inte- 
grated environments with Turbo 
Pascal and we brought that to 
all our languages—to make you 
instantly at ease with our lan- 
guages. (No one else has even 
tried to do that for you.) Read 
these pages. You'll see that the 
revolution continues. 


New! Turbo 
Assembler/Debugger 


It’s Assembler magic and a 
revolution in source-level 
Debugging. 


New Turbo Debugger 
debugs all sizes 


Nothing is too big or too 
small, too simple or too compli- 
cated. Nothing. With EMS 
support, remote debugging, and 
386 virtual machine debugging, 
there’s no limit to the size of 
program you can debug. In fact 
with 386 virtual machine mode, 
debugging takes zero, zip, nil, 
no bytes of conventional mem- 
ory. 


See what's happening 


Multiple overlapping windows 
let you look at code and data 
and work at any level—down to 
CPU or up to source level. You 
can see it all with multiple views 
of the program you're debug- 
ging: source code, variables, 
CPU registers, call stack, 
watches, breakpoints, memory 
dump, and more. And a new 
“session-logging” feature tracks 
and records your every move. 


Eh eR OER. 
... with ournew 


We've brought “what 
if” to Debugging! 


Our breakpoints give you 
more control than anyone 
else’s. Ordinary debuggers only 
get you to a stop, then they 
stop. With ours you control 
When they happen and What 
happens next. When our break- 
points are triggered you can 
simply stop, or you can print 
expressions, run code, send 
messages to the session log, or 
even evaluate an expression 
with user-defined function calls. 
You can control when these 
breakpoints occur because all 
our breakpoints are conditional. 
In plain and simple terms we've 
brought “what if” to debugging. 


Unique Data 
Debugging features 


Plain Vanilla debuggers can 
only give you code debugging. 
Our new Turbo Debugger gives 
you data debugging too. Now 
it’s easy to find the data you 
want. You can browse through 
your data from the simplest 
byte to the hairiest data struc- 
ture, inspect arrays, and walk 
through linked lists. All by point 
and shoot. And once you've 
found the data you want, you 
can get all the information you 
want about it, and you can 
change it. 


Feature highlights 


Multiple overlapping views 
O Source 

O Watches 

Variables 

O Breakpoints 

O Call Stack 

Bo GPU 

O Registers 

1 Numeric Processor 


oO 


Debugger, Assembler, &... 


Shown here is Turbo Debugger in action. 


Memory Dumps 
Session Log 
Files 

User Screen 


Breakpoints 


O Can perform these actions: 
Stop, Print Expression, Run 
Code, Log Expression 

O Can break on arbitrary condi- 
tion, memory changed, pass 
count; attach to specific line 
of code, or apply continuously 
Includes breakpoints, 
tracepoints, watchpoints, and 
conditional breakpoints 


Debug Any Program 


Turbo Pascal, Turbo C, and 
Turbo Assembler 


O EMS support 
386 virtual machine debugging 
1 Remote machine debugging 


O Supports CodeView® compati- 
ble executables 


Data Debugger 

O Follow pointers through linked 
lists 

O Browse through arrays and 
data structures 

O Variables view lets you see all 
defined data 

O Displays type and value infor- 
mation 


i] 


Change data values 


Minimum system requirements: For the IBM 
PS/2 and the IBM family of personal com- 
puters and all 100% compatibles. PC DOS 
(MS DOS) 2.0 or later. 384K minimum. 


New Turbo 
Assembler® lets you 
write the tightest, 
fastest code 


Turbo Assembler is faster 
than other assemblers: not just 
by a little, but by factors. You 
can use it on your existing 
code; it’s fully MASM compati- 
ble, 4.0, 5.0, and 5.1. 

You choose the level of com- 
patibility even MASM can’t do 
that. Turbo Assembler takes you 
beyond MASM, with significant 
new Assembly language exten- 
sions, more complete error 
checking, and full 386 support. 
Turbo Assembler is designed for 
easy interfacing with high-level 
languages like Turbo Pascal and 
Turbo C. (We use Turbo Assem- 
bler on Quattro®, our best- 
selling spreadsheet program; 
now you can write your own 
best-seller with Turbo Assem- 
bler!) 


Turbo Assembler and Turbo 
Debugger are two of our secret 


1) MENU SYSTEM: Global and local menus 
let you easily control and configure your 
programming environment. 


2) VIEWS MENU: Multiple overlapping win- 
dows; 12 different views of the debugging 
session 


3) BREAKPOINT MENU: Powerful breakpoint 
capabilities; you can set local or global 
breakpoints. Device driver for 80386 and 
hardware assist breakpoints. 


4) DATA MENU: Versatile data inspection fea- 
tures; walk through linked lists using point & 
shoot. 


5) MODULE VIEW: One or more module 
views show the multiple files that can make 
up a program. 


6) WATCH WINDOW: Watch variables and 
expressions changes as you step through 
your code. 


7) LOG VIEW: Session log lets you keep 
track of your debug operations, contents of 
windows, and comments to annotate impor- 
tant points. 


weapons, now they can be 
yours. 


Feature highlights 


Factors faster than other 
assemblers 

Full MASM (4.0, 5.0, and 5.1) 
compatibility 

O Significant new assembly lan- 
guage extensions 

O Easy interfacing with high- 
level languages including 
Turbo C and Turbo Pascal 


Turbo Assembler/Debugger: 
only $149.95 


For the IBM PS/2 and the IBM family of per- 
sonal computers and all 100% compatibles. 
PC DOS (MS DOS) 2.0 or later. 256K mini- 
mum. 


*Customer satisfaction is our main concern; 
if within 60 days of purchase this product 
does not perform in accordance with our 
claims, call our customer service department 
and we will arrange a refund. 


t Run on an IBM PS/2 Model 60. 


Prices and specifications subject to change 
without notice. 


All Borland products are trademarks or reg- 
istered trademarks of Borland International. 
Other brand and product names are trade- 
marks or registered trademarks of their 
respective holders. Copyright (c) 1988 
Borland International, Inc. Bl 1279 


...new TurboC 2.0 


New! Turbo C® 2.0 
With integrated 
source-level debugger 


Borland’s revolutionary new 
Turbo C 2.0 is the one C com- 
piler that does it all; nothing is 
half done or not done at 
all—instead, your every pro- 
gramming need is met. (We 
wrote our best-selling word 
processor Sprint with Turbo C 
2.0; when you write with Turbo 
C 2.0, the word is “revolution- 
ary.” 

At better than 16,000 lines a 
minutet, Turbo C 2.0 compiles 
your code 20-30% faster than its 
predecessor Turbo C 1.5 which 
was already faster than any other 
C compiler. 


Make bugs bug off 


Nice bugs are dead bugs, and 
Turbo C 2.0’s integrated source- 
level debugger lets you find 
them and flatten them in a flash. 
You can set multiple breakpoints, 
watch variables and evaluate 
expressions — all from inside 
your integrated C environment. 


Turbo C 2.0 has the 
best of everything 


© Includes the compiler, editor, 
and debugger, all rolled into 
one 

Integrated source-level 
debugger lets you step code, 
watch variables, and set break- 
points 

Develop and debug produc- 
tion-quality code in all six 
memory models 

1 Support for Turbo Assembler 
and Turbo Debugger 

O Make facility with automatic 
dependency checking 
Graphics library with over 70 
graphics functions including 
multi-font graphics text 


width * height 


Debugging in the Turbo environment: shown here an expression is being added to 
the Watch window in Turbo C. The Execution Bar highlights the next line the 


debugger will execute. 


Faster than ever; compiles and 
links 20-30% faster than Turbo 
Cis 

O EMS support 

Numerous levels of error 
checking with built-in Lint 


Turbo C 2.0: only $149.95 


Minimum system requirements: For the IBM 
PS/2* and IBM family of personal computers 
and all 100% compatibles. PC-DOS (MS-DOS) 
2.0 or later. 448K minimum (320K for the com- 
mand-line version). 


Turbo C 2.0 


Professional 


Turbo C 2.0 plus both Turbo 
Assembler & Turbo Debugger: all 
three programs rolled into 
one —the one C package that has 
everything. A complete set of 
tools that caters to every level of 
programming expertise. 


Turbo C Professional: $250 


New! Turbo Pascal® 
5.0 with integrated 
source-level debugger 


Turbo Pascal, the worldwide 
favorite with over a million cop- 
ies out there, just got even 
smarter. The best got better. 
Meet Version 5.0. In a word, it’s 
revolutionary. 


Not only do you go code-rac- 
ing at more than 27,000 lines a 
minutet, you also now go into a 
sophisticated debugging envi- 
ronment—right at source-level. 
It's completely integrated and 
bullet-fast. 


Turbo Pascal’s new integrated 
debugger takes you inside your 
code for fast fixes. You step, 


PROFESSIONAL PROFESSIONAL 


POtiauy porsan? 


...new Turbo Pascal 5.0! 


Shown here is the Evaluate/Modify window of Turbo Pascal: look at expressions, 
examine structured data types, change variables on the fly. 


trace, set multiple breakpoints. 
You modify variables —as you 
debug-—and watch full expres- 
sions at run time. 


Orbit with Units 


Break your code into Units. 
Compiled units make everything 
go faster! Your separately com- 
piled Units carn be shared by 
multiple programs and linked ina 
flash with Turbo Pascal's built-in 
Make utility and smart Linker. (We 
give you a powerful library of 
standard Units including the spec- 
tacular Borland Graphic Interface 
and our state-of-the-art overlay 
manager.) 


PROFESSIONAL 


PROFESSIONAL 


"Onan, = = poussn? 


Debugging: The inside 
story 


Turbo Pascal’s new integrated 
source-level debugger takes you 
inside your code to fix errors fast. 
(Don’t worry about errors, every- 
one makes them; but with the 
right debugger, this one, it’s a fast 
fix.) 


Feature highlights 


O Includes the compiler, editor, 
and debugger, all rolled into 
one 

Integrated source-level 
debugger lets you step code, 
watch variables, and set break- 
points 


O Support for Turbo Assembler & 
Turbo Debugger 


O Overlays, including EMS sup- 
port 

0 JEEE standard floating point 
emulation 

0 Smaller, tighter programs: 
Smart Linker strips both unused 
code and data 

O Procedural types, variables, and 
parameters 

O EMS support for editor 


Turbo Pascal 5.0: only $149.95 


Minimum system requirements: For the IBM 
PS/2* and IBM family of personal computers 
and all 100% compatibles. PC-DOS (MS-DOS) 
2.0 or later. 448K minimum (256K for the com- 
mand-line version). 


Turbo Pascal 


Professional 


Turbo Pascal 5.0 plus both 
Turbo Assembler & Turbo 
Debugger: all three programs 
rolled into one —the one Pascal 
package that has everything. A 
complete set of tools that caters 
to every level of programming 
expertise. 


Turbo Pascal Professional: $250 


As you can see from all these 
brand new programs, the revolu- 
tion is alive and well. Borland 
continues to bring you the best 


For the dealer nearest you, 
call (800) 543-7543. 


BORLAND 


LISTING 1: ENGINE.PAS 


UNIT Engine; 
{$V-} 


(III ITI ARI III III IIR III IIIA III AISI ISSA ASIII ADE 


SEARCH ENGINE 
Input Parameters: 
Mask : The file specification to search for 
May contain wildcards 
File attribute to search for 
Procedure to process each found file 


Attr: 
Proc : 
Ouput Parameters: 

ErrorCode : Contains the final error code. 


| Aolahalahalahehalalalalalehahalelslaieieleiaieleisieisisiaieleieieieieleleisieisisisisisisisieisisieieieichsieieled 


{ Golahalhahalelelelalalaiaiahalaiaiaiaioleled ) 


(**) INTERFACE ce*) 


| Galahabalalalalahelehaielelalehehsiainlelaled | 


USES DOS; 


TYPE 
ProcType PROCEDURE (VAR S : SearchRec; P : PathStr); 
FullNameStr = STRING[12); 


PROCEDURE SearchEngine(Mask : PathStr; 
Attr : Byte; 
Proc : ProcType; 
VAR ErrorCode : Byte); 


FUNCTION GoodDirectory(S : SearchRec) : Boolean; 
PROCEDURE ShrinkPath(VAR path : PathStr); 
PROCEDURE ErrorMessage(ErrCode : Byte); 
PROCEDURE SearchEngineAll(path : PathStr; 

Mask : FullNameStr; 

Attr : Byte; 

Proc : ProcType; 

VAR ErrorCode : Byte); 


( Gchahebalahalahahshelalaletelelelelalelelaed ) 


(**) IMPLEMENTATION (**) 
(Set RR RRR RR RR RIE) 


VAR 
EngineMask : FullNameStr; 
EngineAttr : Byte; 
EngineProc : ProcType; 
EngineCode : Byte; 


PROCEDURE SearchEngine(Mask : PathStr; 
Attr : Byte; 
Proc : ProcType; 

VAR ErrorCode : Byte); 


earchRec; 
athStr; 
ExtStr; 


FSplit (Mask, P, Mask, Ext); 
Mask := Mask + Ext; 
FindFirst(P + Mask, Attr, $); 
IF DosError <> O THEN 
BEGIN 
ErrorCode := DosError; 
Exit; 
END; 


WHILE DosError = 0 DO 
BEGIN 
Proc(S, P); 
FindNext(S); 
END; 
IF DosError = 18 THEN ErrorCode := 0 
ELSE ErrorCode := DosError; 
END; 


FUNCTION GoodDirectory(S : SearchRec) : Boolean; 
BEGIN 

GoodDirectory := (S.name <> '.') AND 

(S.name <> '..') AND 

(S.Attr AND Directory = Directory); 
END; 


PROCEDURE ShrinkPath(VAR path : PathStr); 
VAR P : Byte; 
Dummy : NameStr; 
BEGIN 
FSplit(path, path, Dumny, Dumny); 
Dec(path [0] ); 
END; 


{$F+} PROCEDURE SearchOneDir(VAR S : SearchRec; P : PathStr); {($F-} 


{Recursive procedure to search one directory} 
BEGIN 
IF Goodirectory(S) THEN 
BEGIN 
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P z= P + S.name; 
SearchEngine(P + '\'! + EngineMask, EngineAttr, 
EngineProc, EngineCode); 
SearchEngine(P + '\*.*', Directory OR Archive, 
SearchOneDir, EngineCode); 
END; 
END; 


PROCEDURE SearchEngineAl (path : PathStr; 
Mask : FullNameStr; 
Attr : Byte; 
Proc : ProcType; 
VAR ErrorCode : Byte); 
BEGIN 
(*Set up Unit global variables for use in 
recursive directory search procedure*) 
EngineMask := Mask; 
EngineProc Proc; 
EngineAttr := Attr; 
SearchEngine(path + Mask, Attr, Proc, ErrorCode); 
SearchEngine 
(path + '*.*', Directory OR Attr, SearchOneDir, ErrorCode); 
ErrorCode := EngineCode; 
END; 


PROCEDURE ErrorMessage(ErrCode : Byte); 
BEGIN 

CASE ErrCode OF 
3 {OK -- no error} 
WriteLn('File not found'); 
WriteLn('Path not found'); 
WriteLn('Access denied'); 
WriteLn('Invalid handle'); 
WriteLn('Not enough memory'); 
10 : WriteLn('Invalid environment'); 
11: WriteLn('Invalid format'); 


eovIwnoe 


ae ae ae ae oe oe 


acres {OK -- merely "no more files") 
ELSE WriteLn('ERROR #', ErrCode); 
END; 
END; 


END. 


LISTING 2: DIRSUM.PAS 


{$R-,S+,1+,D+,F-,V-,B-,N-,L+ } 
{$M 2048,0,0 } 

PROGRAM DirSum; 

(APRRARRARAARAARAEAEAARRERAEAEREEEREERERERERERERRRRAREREE ) 
(* Uses SearchEngine to write the names of all files *) 
(* in the current directory and display the total disk *) 
(* space that they occupy. *) 


(ARRRERAARARRERRRRRAAAARRERARARARRRRAAR ARERR AEAR EER EERERE ) 
USES DOS, ENGINE; 


VAR 
Template : PathStr; 
ErrorCode : Byte; 
Total : LongInt; 


{$F+} PROCEDURE WriteIt(VAR S : SearchRec; P : PathStr); (SF-} 
BEGIN WriteLn(S.name); Total := Total + S.Size END; 


BEGIN 

Total := 0; 

GetDir(0, Template); 

IF Length(Template) = 3 THEN Dec(Template[0) ); 

{Avoid ending up with "C:\\*.*"!1} 

Template := Template + '\*.*'; 

SearchEngine(Template, AnyFile, Writelt, ErrorCode); 

IF ErrorCode <> 0 THEN ErrorMessage(ErrorCode) ELSE 

Writeln('Total size of displayed files: ',Total : 8); 

END. 


LISTING 3: WHERE.PAS 


{$R- ,S+,1+,D+,F-,V-,B-,N-,L+ > 
{sm $4000,0,0) 

PROGRAM where; 

(FRPARRATRAREREREAARERAREAAAREERARAERAEERRARARRERREE REED > 
(* Uses SearchEngine to find and display matching files *) 
(* in any subdirectory and total their sizes (e.g., to *) 
(* find all Pascal files, execute WHERE *.PAS). my 
(FPRRERERREREREDERREAREERERERRERERERERERERRERREERRRERERE ) 


USES DOS, Engine; 


VAR 


template, path : STRING; 
ErrCode : Byte; 
Total : LongInt; 


($F+} PROCEDURE ShowFile(VAR S$ : 
BEGIN 

WriteLn(path + S.Name); 

Total := Total + S.Size 
END; 


SearchRec; path : PathStr); 


Sophisticated User Interfaces in Minutes! 


Put magic in your programs with ¢ 


“rg 
| 


The World’s Best Code Generator! 


Windows for data-entry (with full-featured editing), context-sensitive help, Lotus-style menus, pop- 
up menus, and pull-down menu systems. Overlay them. Scroll within them. 


Users and critics say it all!... 


“.. the best I've used ... The code that it generates is excellent, with every feature you 
could conceivably desire. ... if you have problems, they give excellent technical advice 
over the phone. ... It saves time, is flexible and produces screens which are state of the 
Orie 7 Sally Stott, Software Developer 


“... the best screen generator on the market.” George Kwascha, TUG Lines, Nov/Dec 87 


“... the Cadillac of prototyping tools for Turbo Pascal. ... Unlike the others, turbo MAGIC 
is extremely flexible. ... [it] clearly offers the greatest variety of options.” 


Jim Powell, Computer Language, Jun 87 


“Fast automatic updating of dependent fields adds flair to your input screens. ... 
turboMAGIC will be a blessing for programmers who would rather not write the user 
interface for every program.” Neil Rubenking, PC Magazine, 24 Feb 87 


“Twas impressed with the turbo MAGIC package. ... the procedures created by turbo MAGIC 
are well commented and easy to add to your own code.” 
Kathleen Williams, Turbo Tech Report, May/Jun 87 


“... definitely a recommended program for any Turbo Pascal programmer, novice or expert.” 
Terry Lovegrove, Library Hi Tech News, Oct 87 


ORDER your Magic TODAY! Only $199. 
CALL TOLL FREE 800-225-3165 or 205-342-7026 


sophisticated 
software 


esd 


6586 Old Shell Road, Mobile, AL 36608 
Requires 512K IBM PC compatible and Turbo Pascal 4.0. 30-Day Money Back Guarantee. Foreign orders add $15. 


SEARCH ENGINE 
continued from page 28 


TWO LITTLE ENGINES 


Keep the compiled ENGINE.TPU handy; you'll find 
yourself thinking of new ways to use it all the time. 
When you need to search for files within a single di- 
rectory, use SearchEngine. For searches that traverse 
a tree or a subtree, use SearchEngineAll. 

Unit Engine illustrates an important principle of 
software development: The more general a tool, the 
more different problems it solves, and the more time 
that it saves you. Turbo Pascal 5.0’s procedural types 
make possible the creation of truly general tools 
whose tasks can be specified at runtime. Other “en- 
gines” suggest themselves, such as a graphics func- 
tion plot engine that receives a function to plot via a 
function parameter, or a general-purpose sort unit 
that takes a function that specifies which of two data 
items is considered greater than the other on some 
sort sequence. Once you start thinking of program 
statements as just another kind of data, these kinds 
of solutions will seem the natural way to do business 
in a system-level language such as Turbo Pascal 5.0. 


Neil Rubenking is a professional Pascal programmer and 
wniter. He is a contributing editor for PC Magazine, and 
can be found daily on Borland’s CompuServe forums an- 
swering Turbo Pascal questions. 


Listings may be downloaded from Library 1 of Compu- 
Serve forum BPROGA, as PASENG.ARC. 


“The cost involved, in writing one 
of these geometric routines, is more than 
the price of the TurboGeometry Library.” 


Are you programming or planning to program CAD/CAM 
or graphics applications? Many hours, even days, can be 
spent in writing and debugging geometric routines. 
TurboGeometry Library can relieve you of those time 
consuming tasks that are part and parcel of every 
CAD/CAM or graphics program. There are over 150 
routines in the library, supported by example programs 
and a 400 page manual. The source code is included. 30 
day guarantee. Need IBMPC or Compatible, Turbo Pascal 
4.0, Turbo C, or MS C. $149.95 plus $5.00 S&H in US. 
VISA, MasterCard, Check, PO, MO. No COD’s Send for 
additional information or call 214-423-7288. 


Disk Software, Inc., 2116 E. Arapaho #487 
Richardson, Texas USA 75081 


“In CAD/CAM or graphics, it all comes down 
to using geometry” 
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PROCEDURE Validate; 
{Validate the command line parameter} 
VAR P : Byte; 
Ext : ExtStr; 
BEGIN 
IF ParamCount <> 1 THEN 
BEGIN 
WriteLn( SYNTAX: 
Halt; 
END; 
FSplit(ParamStr(1), path, template, Ext); 
IF Length(path) = 2 THEN path := path + '\'; 
template := template + Ext; 
(*IF no path specified, search from root of 
current volume*) 
IF path = '' THEN 
BEGIN 
GetDir(0, path); 
IF Length(path) = 2 THEN path := path + '\' 
ELSE path(0) := #3; 
END; 
END; 


"WHERE [path] filespec"'); 


BEGIN 
Total := 0; 
Validate; 
WriteLn 
('Searching for "', template, '" in or below "', path, '"'); 
SearchEngineAll(path, template, Archive, ShowFile, ErrCode); 
Writeln 
('These files occupy ',Total : 
END. 


8,' bytes of disk space.') 


LISTING 4: DELBAK.PAS 


{($R- ,S+,1+,D+,F-,V-,B-,N-,L+ > 
{$4 $4000,0,0) 
PROGRAM Del Bak; 


(PRRRRRRAERR RARER ARARAARRARAR ARERR RRRERER EERE ERE RE RREEEE ) 


(* Uses SearchEngine to find and delete all *.BAK files *) 
* 


(* in any subdirectory in the current volume. 
(HRRRERERERERERRARRERREARRARRERARRERERRERERERRRRRERERRERE ) 


USES DOS, Engine; 


VAR 
path : PathStr; 
ErrCode : Byte; 
Number : Integer; 
Size : LongInt; 


{$F+} PROCEDURE DelFile(VAR S : SearchRec; path : PathStr); {($F-} 
VAR F : FILE; 
BEGIN 
Inc(Size, S.Size); 
Assign(F, path + S.name); 
Erase(F); 
Inc(Number ); 
END; 


PROCEDURE Initialize; 
BEGIN 
Number := 0; 
Size := 0; 
GetDir(0, path); 
IF Length(path) = 2 THEN path := path + '\' 
ELSE path(0] := #3; 
WriteLn('Going to delete ALL *.BAK files in the current volume.'); 
WriteLn('Press <Return> to proceed, “Break to stop.'); 
ReadLn; 
END; 


BEGIN 
Initialize; 
SearchEngineAl|(path, '*.bak', AnyFile, DelFile, ErrCode); 
WriteLn 
(‘Erased ',Number,' *.BAK files for a saving of ',Size,' bytes'); 
END. 


PUT YOUR BEST 
FACE FORWARD 


With Our New User Interface Manager 


The American Flying Corp. 


Edit Options 


Africa 


Asia 


——-U.S, States: 


The most important part of your program furope | Monescts -Miselselppi Missouri More Than Just A Pretty Face. 
is the user interface. . . Getting that face PR re Facelt faces are powerful and flexible. Use 


right used to be the hardest part of appli- rar 


‘Syracuse 


them to design front-ends, build context- 


cation development. Not any more. = 


Introducing Facelt™ Creating menus 
has never been easier with this new state-of- 
the-art user interface manager. Facelt’s totally 
different approach to menu creation gives 
you perfect faces every time. You simply supply 
the data and Facelt does the rest. It creates the face you need— 
pop-ups, pull-downs, horizontal menus, help windows, dialog 
boxes or multiple column menus, automatically, based on the data 
you provide. And don’t worry if your files contain lots of text, Facelt 
has built-in virtual windowing and scrolling capabilities. 


How Facelt Works. 

1. Define the contents of your menus using any editor or import 

the data directly from a .DBF file. 

2. Then Facelt, using this data, designs the interface you want. 

3. Use the interface as is. Or, go into the interactive mode to change 

it on the screen. Take total control over menu customization. Change 
window shapes, 

Pop-up border styles 

and color every 

Help Window  €lement of the 

menu right 

down to the 

individual 

menu item. 

4. You're done. The Facelt faces are ready to be called directly 

from your program. 


Borland ASCII text Pull-down 


Microsoft DBF file 


dBASE 


Horizontal 


Grid 


Laying Out Different Menuing Systems Now Takes 
Minutes. Using a new technology called “dynamic menuing’ 
you get a complete menuing system in minutes. Facelt automat- 
ically draws the boxes, puts the data into the menus, links them 
together, positions them, handles all cursor control, saves and 
restores the screen and provides mouse support. Create menus by 
specifying any or all records or line numbers. Plus, because all 
Facelt faces are live menus and not static, you can customize or 
totally redesign them right there on the screen. Turn a pull- 
down into a Lotus® style menu in seconds without any coding 
or compiling! 


Build this interface instantly. Simply display the 
top level menu. Then interactively link the other 
menus together, automatically. 


sensitive online help systems or for pro- 
totyping. Facelt menus can return to 
your program the highlighted item, the 
name of the menu and the number of 
the item selected or a return string from 
another menu. 


Facelt Speaks Your Language. Facelt includes the lan- 
guage specific modules (LSMS) for all Borland and Microsoft 


languages, dBASE" FoxBASE +™ Clipper,” 
Quicksilver™ DBXL™ and Emerald Bay's Face} 
Eagle™ LSMS provide the two-way 

communication between your appli- 19, 
cation and the Facelt engine. Facelt 
menus are called directly from your 


programming language so there's no 
need for wake-up codes or hot keys. 


The Perfect Turbo Companion. 
Make your programs look like the Turbo environment you program 
in. Facelt has no royalties or runtime fees and is backed by our 

30 day unconditional money back guarantee. So whether you 
program for yourself, your company or other people, Facelt will 
create the right face and give your application the look it deserves. 


Facelt 


and put your best face forward. 


Only $99 
Call Today 212-787-6633 


Black & White International, Inc. 
PO. Box 21108 
New York, NY 10129 


Facelt Features: Scrolling menus with scroll bars, headers and footers, onscreen WYSIWYG menu customization, full 
color support, separators/blank items, initial character selection, item/menu level help, default/manual placement 
unavailable items, return strings, runtime module uses only 19K. Supports: The IBM® PC, XT, AT PS/2® and true 
compatibles, EMS 3.2 and above, 43 line EGA mode, 50 line VGA mode, 40 column mode, Microsoft mouse 
compatible. Requires DOS 2.1 or higher. Not copy protected. 


Facelt is a trademark of Black & White International, Inc. Other brand and product names are trademarks or 
registered trademarks of their respective holders. 


THE RETURN OF 


OVERLAYS 


Turbo Pascal 5.0 uses disk storage 
and EMS to run your biggest program 


in as little memory as possible. 


Bruce F. Webster 


Overlays vanished in version 4.0 of Turbo 
Pascal because the internal changes to 
memory allocation made support of the 
old 3.0-style overlays impossible. With the 
advent of Turbo Pascal 5.0, however, a 
new and much better implementation of 
overlays has now appeared. In this article, we'll take 
a close look at how the 5.0-style overlays work, and 
the ways that you can use them. 


SQUARE ONE 


THE MEMORY GAME 


People who first met Turbo Pascal with version 4.0 
may well be asking, “What are overlays anyway, and 
why would I want to use them?” Let’s take the sec- 
ond part of the question first. When a Turbo Pascal 
program is run, the main program and all of the 
units that it uses are loaded into memory. The main 
program and each unit occupy separate code segments 
that can each be up to 64K in size. All declared vari- 
ables are created in memory within a single data seg- 
ment, which also has a 64K size limit. In addition, a 
program stack is allocated; its size is determined 
either by the Options/Compiler/Memory Size/Stack 
command or by the $M compiler directive in the 
main program. Finally, any remaining memory can 
be allocated to the heap through $M; this is the loca- 
tion in memory where any dynamic variables (which 
are created using the New or GetMem procedures) 
are allocated. Of course, a certain amount of mem- 
ory is already occupied by DOS, any memory- 
resident programs you might have already loaded, 
and (if the programs are running under the Turbo 
Pascal Integrated Environment) by Turbo Pascal 
itself. 

Although this may seem like a lot to have in mem- 
ory all at once, most of the time there is memory 
room to spare. However, you can run out of available 
memory: 
© If your program becomes very large; 


e If you need to dynamically allocate large data 
structures; or 


e If you have other programs loaded at the same 
time. 
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If your computer doesn’t have a lot of memory, your 
program may not load; if it does load, it may halt 
prematurely with a memory allocation error. 

A solution to this problem is to break your pro- 
gram up into relatively independent chunks, and 
then load those chunks into memory as they are 
needed. Once a given chunk is no longer needed, 
the memory that it formerly occupied can be reused 
for a different chunk. 

This brings us back to the first part of the earlier 
question, “What are overlays?” Basically, overlays are 
those “chunks” I’ve been talking about. More specif- 
ically, overlays are separately compiled Turbo Pascal 
units that are loaded into memory as they are need- 
ed, and then removed from memory until they are 
required again. This process is handled for you in a 
painless and generally invisible way—you simply tell 
Turbo Pascal which units are to be used as overlays, 
and then perform a few other preparations. (For 
more information about units in general, see “Get- 
ting to Know Units,” TURBO TECHNIX, November/ 
December, 1987.) 


HOW OVERLAYS WORK 


When you compile a program that uses overlays, all 
of the executable code for the overlay units (the units 
that are designated as overlays) is written to an over- 
lay file rather than to the usual .EXE file. The overlay 
file has the same filename as the .EXE file, with the 
extension .OVR instead of .EXE. 

At the same time, a unit known as the “overlay 
manager” is linked into your program. The overlay 
manager determines which overlay unit or units 
should be in memory at any given moment, and 
loads them in from the overlay file as needed. 

When a program that uses overlays is run, the 
main program, the overlay manager, and all non- 
overlaid units are loaded into memory where they 
remain while the program executes. The data seg- 
ment and the stack are also created and used in the 
same manner as with a nonoverlaid application. 
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Lahey Computer Systems, Inc. 
Sets a New FORTRAN Standard! 


Introducing the latest addition to our line of PC FORTRAN Language Systems— 


Lahey Personal FORTRAN 77 Version 2.0 


What You Get When 
You Purchase 

Lahey Personal 
FORTRAN: 


Lahey Experience. 
We are experts in designing 
and implementing FORTRAN 
Language Systems. Lahey 
has been producing 
mainframe implementations 
since 1967 and PC 
FORTRANSs (F77L) since 1984. 
In fact, F77L was named the 3 
“EDITOR’S CHOICE” among PC 
FORTRANs by PC Magazine. This 20- 
year span of specialization has been 
incorporated into the design of our 
revolutionary Lahey Personal FORTRAN 77. 


LAHEY SLASHES COMPILATION TIME. 
Compilation times (in seconds) for wer are Program (WHETS3H FOR) 


Test ¢ 


fan IBM AT ing at 6Mhz with 80287 t au 5 T 91} T T T 


bit Lahey Personal FORTRAN 77 Version 2.0 ($95) ae 11.57 


Microsoft 


FORTRAN Version 4.0 ($150) 


Ryan McFarland Fortran version 2.11 ($595) 


Customer Support: 


Our philosophy is that customer relationships begin, rather than end, at the 
point of sale. Services include free technical support, electronic bulletin board 
for fast service and information access, and newsletters to keep you up to 
date on our latest developments. 


Purchasing the Lahey Personal FORTRAN 77 gives you software designed 
by FORTRAN experts, a feature-loaded product with industry-leading 
compilation speed, and quality technical support; all for $95. 


International Representatives: Australia: Comp. Transitions, Tel. (03)5372786 * Canada: Barry Mooney & Assoc., 
Tel. (902)6652941 * Denmark: Ravenholm Computing, Tel. (02)887249 * England: Grey Matter Ltd., Tel. (0364)53499 
* Holland: Lemax Co. BV. (02968)4210 * Japan: Microsoftware Inc., Tel. (03)813822 * Norway: Polysoft A.S 
(03)892240 © Switzerland: DST Comp. Services, Tel. (022)989188 


MS-DOS & MS FORTRAN are trademarks of Microsoft Corporation 


We have a complete line of PC FORTRAN Language Systems. 
For developing or porting programs there is no substitute for a Lahey. 


Lahey Personal......So much for so little $95 
$477 
$695 
$895 


“‘Editor’s Choice’’ PC Magazine 

Ability to write programs as large as 15 MB 

New 32-bit—Programs up to 4GB on 80386 
CALL FOR MORE INFORMATION 


Feature Loaded: 


Full implementation of the 
ANSI X3.9-1978 FORTRAN 
Standard 


¢ Fast Compilation (see chart) 


Popular Language 
Extensions highlighted in the 
manual 

Source On-Line Debugger 
English Diagnostics and 
Warning Messages 
LOGICAL"1, LOGICAL*4 
INTEGER*2, INTEGER*4 
REAL*4, REAL"8, and 
DOUBLE PRECISION 
COMPLEX*8, COMPLEX*16 
Recursion 

31-Character Names 

Trailing Comments 

Cross Reference and Source 
Listings 

64 KB Generated Code 

64 KB Stack Storage 

64 KB Commons, Constants 
and Saved Local Data 

Math coprocessor emulation 
runs with or without a 

math coprocessor chip 
400-Page User Manual 


SYSTEM REQUIREMENTS: 
256K Ram MS-DOS (2.0 or later) 


*95 


Lahey is setting the 
PC FORTRAN Standard. 


TO ORDER 


1-800-548-4778 


(specify disk size) 
Lahey Computer Systems, Inc. 
PO. Box 6091 
Incline Village, NV 89450 
Telephone: (702) 831-2500 
TELEX: 9102401256 
FAX: (702) 831-8123 


Lahey 


Computer Systems CY 


OVERLAYS WITH 5.0 
continued from page 38 


When a program that uses over- 
lays is run, however, part of the 
heap is taken away and set aside 
as the overlay buffer. By default, 
this buffer is just big enough to 
hold the largest overlay unit; how- 
ever, you can specify a larger 
buffer to improve performance 
during unit loading. The overlay 
manager then loads as many units 
as possible into the overlay buffer. 

When a routine in an overlay 
unit is called, the overlay manager 
checks if that unit is already in 
memory. If the unit is not in mem- 
ory, the overlay manager loads the 
requested unit from the overlay 
file into the overlay buffer, and re- 
moves other units from the buffer 
as needed. If the manager has a 
choice of units to swap out, it’s 
“smart” enough to remove the 
unit that was least recently called, 
based upon the assumption that 


the other units in the buffer are 
more likely to be called. This pro- 
cess is performed automatically, 
without any specific load or un- 
load requests from your program. 
The net benefit is that a large 
program can run in a limited 
memory space. While the costs are 
four-fold, they can be minimized 
by some attention to detail. First, 
your program may need to be re- 
structured in order to make it fea- 
sible to use certain units as over- 
lays. (This step may actually im- 
prove your overall program 
design.) Second, a disk access oc- 
curs each time a unit is loaded 
from disk into memory. These 
disk accesses can be minimized by 
either increasing the size of the 
overlay buffer, or (if your com- 
puter has expanded memory) by 
instructing the overlay manager to 
load the overlay file (not the over- 
lay buffer) into expanded mem- 
ory. Third, the overlay scheme re- 


Beat the Deadlines and 


thrill them with Performance!! 


Now there is a better, more productive way to create programs 
that relieves your implementation worries and frees your mind, 
so conquering your next big project becomes child’s play! 
Whether you program in Turbo Pascal or Turbo C, we’ve got 
you covered. Introducing The Developer’s Library Series - not 
just a collection of handy routines like most libraries, but a 
complete programming environment. Both libraries are 
compatible, which makes switching from one language to 


another a snap. 


Turbo C or Turbo Pascal 
Developer’s Libraries 
Over 120 routines in each library for development of commer- 


cial software. 


Includes routines for: networks, multi-user file 


management, menuing, utilities, sample applications,and much 
more. Complete with 450 page text from Howard W. Sams 
Publishing and source code on diskette for IBM PC. 


Only $6925 can 


New ! The Floppy Librarian 


A must for anyone with lots of floppy disks to manage! 
Maintains physical locations of floppy disks, lists files stored on 
any and all disks, tracks file changes and backups and more! 


Stop asking, "Where is it?"! 


Order Now!. Only $2995 


i 


Perpetual Data Systems, Inc. 


For IBM PC’s & Compatibles 


63 Keystone Ave. Suite 206 
Reno, Nevada 89503 
(702) 348-8600 
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quires that far calls be used 
throughout all procedure call 
chains that extend into an overlay. 
It also exacts an additional perfor- 
mance penalty when string literals 
and set constants are passed as 
parameters. Fourth, when floating 
point emulation is used, the inter- 
rupt vector “backpatching” 
scheme is reinitialized each time 
an overlay is loaded into memory. 
A small performance overhead oc- 
curs when the overlay’s floating 
point code is executed for the first 
time. 


GET READY TO OVERLAY 


Several steps are necessary in 
order to use overlays. 


Units first. The program must first 
be structured to make overlays 
possible. Since only complete 
units can be treated as overlays, 
all sections that are to be overlaid 
must be broken out and put into 
units (if they’re not in units al- 
ready). Overlaid units should be 
relatively independent—they 
should call one another’s routines 
as little as possible, but preferably, 
not at all. If one overlay calls rou- 
tines in another overlay, disk 
“thrashing” may occur—where a 
distraught overlay manager loads 
one overlay and then another in 
rapid succession—bringing pro- 
gram performance to its knees. 
The Overlay Unit. The main pro- 
gram must use the Overlay unit, 
which is part of the TURBO.TPL 
library. Overlay contains the over- 
lay manager and provides several 
routines that allow the program to 
communicate with the overlay 
manager. Also, the unit name 
Overlay must appear in the USES 
clause before the names of any of 
the overlaid units. Preferably, 
Overlay should be the first unit 
named. 


Compiler directives. Each unit 
that will be used as an overlay unit 
must be named in its own {$O} 
compiler directive. These direc- 
tives appear in the main program 
after the USES clause, but before 
anything else. The format is 
simply {$0 <unitname>}, where 
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Mainframe Power for your PC! 


If you need or are accustomed to the 
throughput of a 32-bit mini, including any of 
DEC’s VAX series, MicroWay has great news 
for you. The combination of our NDP compilers 
and our mW1167 numeric coprocessor gives 
your 386 PC, VAX speed! Jf you don't own a 
386 PC, we provide a number of economical 
PC and AT upgrade paths. 

Many of our NDP Fortran-386 users are 
reporting turn around times that are two to six 
times faster than their VAX. The exact times 
are a function of the VAX processor being used, 
the speed of the 386, the number of users being 
served by the VAX, and the coprocessor being 
used with the 386. There are currently over 400 
developers using our NDP tools to port 32-bit 
applications. To help the 386/1 167 engineering 
standard emerge, MicroWay is co-marketing 
several mainframe applications that have been 
ported by our customers. In addition, this ad in- 


Dr. Robert Atwell, a leading defense scientist, 
calculates that NDP Fortran-386 is currently 
saving him $12,000 per month in rentals of 
VAX hardware and software while doubling 
his productivity! 


Fred Ziegler of AspenTech in Cambridge, 
Mass. reports "] ported 900,000 lines of 
Fortran source in two weeks without a single 
problem!" AspenTech’s Chemical Modeling 
System is in use on mainframes worldwide 
and is probably the largest application to ever 
run on an Intel processor. 


Dr. Jerry Ginsberg of Georgia Tech reports 

"My problems run a factor of six faster using 

NDP Fortran-386 on an mW1167 equipped 
386/20 than they do on my MicroVAX II." 


troduces the first of many utilities that will ease 
the porting of your favorite in-house programs. 
These include tools like NDP-Plot, which 
provides CalComp compatible screen and 
printer graphics, and NDP Windows. 
MicroWay has mW1167 boards in stock that 
run on the Compaq 386/20, IBM PS2/80, 
Tandy 4000, AT&T 6386, Acer 386/20, Everex 
Step 386/16(20), H.P. Vectra RS/16(20) and 
others. We now have a new board for the Com- 
pag 386/20 which combines an 1167 with VGA 
support that is register compatible with IBM — 
the "SlotSaver". It features an extended 


800x600 high res mode that is ideal for 386 
workstations. 

Finally, we still offer the 16-bit software and 
hardware which made us famous. If you owna 
PC or AT and are looking for the best 
8087/80287 support on the market, call (508) 
746-7341 and we'll send you our full catalog. 


32-Bit Compilers and Tools 


NDP Fortran-386™ and NDP C-386™ Com- 
pilers generate globally optimized mainframe 
quality code and run in 386 protected mode 
under PharLap extended MS-DOS, UNIX, or 
XENIX. The memory model employed uses 2 
segments, each of which can be up to 4 
gigabytes in length. They generate code for the 
80287, 80387, or mW1167. Both compilers in- 
clude high speed EGA graphics extensions 
written in C that perform BASIC-like screen 
OPOTANONS sic 5 ce aces eee eins = $595 each 


¢ NDP Fortran-386™ Full implementation of 
FORTRAN-77 with Berkeley 4.2, VAX/VMS 
and Fortran-66 extensions. 


¢ NDP C-386™ Fullimplementation of AT&T's 
PCC with Microsoft and ANSI extensions. 


NDP Package Pricing: 


387FastPAK-16: NDP Compiler, PharLap, 
and 80387-16 Coprocessor $ 


1167FastPAK-16: NDP Compiler, PharLap, 


and mW1167-16 Coprocessor $1695 


NDP Windows™ — NDP Windows includes 80 
functions that let you create, store, and recall 
menus and windows. It works with NDP C-386 
and drives all the popular graphics adapters. 
Library ..... $125, C Source ..... $250 


NDP Plot™ — Calcomp compatible plot pack- 
age that is callable from NDP Fortran. It in- 
cludes drivers for the most popular plotters and 
printers and works with CGA, Hercules, EGA 
ENO VGA sc 3 dacoutecs chemi ale aslo aire $325 


NDP/FFT™ — Includes 40 fast running, hand 
coded algorithms for single and double dimen- 
sioned FFTs which take advantage of the 32- 
bit addressing of the 386 or your hard disk. Call- 
able from NDP Fortran or NDP C with 1167 and 


387,GUDDOM. osmpacoatrumomsmonetenucrns $250 
387FFT for 16-bit compilers............ $250 
387BASIC™ — A 16-bit Microsoft compatible 


Basic Compiler that generates the smallest 
.EXE files and the fastest running numeric code 
OME MAKE. 26 cn occ aves t cage nes $249 


MicroWay * 


80386 Support 


Parallel Processing 


Monoputer™ 

The world's most popular Transputer develop- 
ment product runs all MicroWay Transputer 
software using either a T414 or T800. The T800 
processor has built-in numerics and provides 
performance comparable to an 80386 running 
at 20 MHz with an mW1 167. The new 3L Paral- 
lel C and Fortran Compilers makes this an 
especially attractive porting environment. Can 
be upgraded to 2 megabytes. 


Monoputer with T414 (0 MB) ........ $995 
Monoputer with T800 (0 MB) ....... $1495 
Quadputer™ 


This board for the XT, AT, or 386 can be pur- 
chased with 2, 3 or 4 Transputers and 1,4 0r8 
megabytes of memory per Transputer. Two or 
more Quadputers can be linked together to 
build networks with mainframe power which 
use up to 36 Transputers. One customer's real- 
time financial application has gone from 8 
hours on a mainframe to 16 minutes on a sys- 
tem containing five Quadputers. . . . from $3495 


Labs Compilers and Applications 
MicroWay and 3L offer Parallel languages for 
the Monoputer and Quadputer. 


MicroWay ParallelC ............... $595 
MicroWay Occam2 ................. $495 
gs | BL Tell] | CE rae eA ee re Ae $895 
3L Parallel Fortran: .<.s2<<<200.5<<8% $895 


pField — A specialty finite element analysis 
package targeted at Transputer networks. 
Ideally suited to take advantage of the 6 
Megaflop speed of the Quadputer...... $1600 


Call (508) 746-7341 for our 
free catalog! 


Numeric Coprocessors 


mW1167™ — Built at MicroWay using Weitek 
components and an 80387 socket. 


TOWVANG F LG oa bien sth.e > eta s eins $995 
MIG So eO sett wen sade ee ails $1595 
mW1167/VGA-20 "SlotSaver" ...... $1995 
OG eit cette tela 5 dsc,8ua Wiens © eee $99 
eae Fahd dics cs otis bee ado aca $154 
CUPPA ee era cis heise ols a ale caeaies $239 
DUE RN ON stale stds serait saualeen sareeeete $295 
COGENT ACen cue 05a ato, 2 acts Dame $475 
SOT HLO ois, ecin Sc a5,5 oaks eee intoe $725 
287Turbo-12 (for AT compatibles) ... . $450 
DRAM io ccsiccchs athe. a ect open weg mypraty CALL 


(All of our Intel coprocessors include 87Test.) 


PC and AT Accelerators 


MicroWay builds a number of 8086 and 80286- 
based PC accelerators that are backed up by 
the best customer support in the industry. 


Number Smasher™ (8087 & 512K) ..$499 
FastCACHE-286/9 MHz............ $299 
FastCACHE-286/12 MHz........... $399 
SuperCACHE-286/12 MHz ......... $499 
Intel Inboard™ PC (1 MB).......... $950 


Intelligent Serial Controllers 


MicroWay's AT4™, AT8™, andAT16™ are the 
fastest 80186-based intelligent serial control- 
lers on the market. They come with drivers for 
UNIX, XENIX, and PC MOS. 

AT4...$795 AT8...$995 AT16... $1295 


32-Bit Applications 


COSMOS-M/386 — SRAC's finite element 
package for the 80386 with an 80387 or 
mW1167 provides mainframe speed and 
capacity. Turn around times rival the VAX 8650 
and are 6 to 15 times that of an AT: from $995 


PSTAT-386 — This mainframe statistics pack- 
age has been used by government and in- 
dustry for 20 years. The full version was ported. 
Requires 4 to 6 megabytes of memory: $1495 
NDP/NAG™ — Features a library of 800 en- 


gineering and scientific numerical algorithms. 
Callable from NDP Fortran............. $895 


The World Leader in PC Numerics 


P.O. Box 79, Kingston, MA 02364 USA (508) 746-7341 
32 High St., Kingston-Upon-Thames, U.K., 01-541-5466 
Sr Coonates: NSW, Australia 02-439-8400 
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unitname is the unit’s name as it 
appears in the USES clause. 

Also, an {$0+} compiler direc- 
tive must be placed within each 
overlaid unit in order to show to 
the linker that the unit is to be 
treated as an overlay. 


Far calls. The main program and 
all units should be compiled with 
the Options/Compile/Force far 
calls toggle set to On, or with the 
{$F+} directive present in each 
file. Far calls must be used with all 
of the routines that call the rou- 
tines in overlaid units, with all of 
the routines that call those rou- 
tines, and so on, back to the main 
body of the program. The safest 
way to enforce this requirement 
is simply to use far calls through- 
out the entire program. 


The .OVR filename. The main 
program must tell the overlay 
manager the filename of the 
-OVR overlay file by calling Ovr- 


{$F+} 
program Ship; 
uses 


Overlay, Graph, MainLib, GamelInit, 


Init (one of the routines in the 
Overlay unit) with the appropriate 
filename in OvrInit’s string pa- 
rameter. The OvrResult variable 
in the Overlay unit is set to the re- 
sult code; this step allows the pro- 
gram to detect errors and then 
gracefully exit if the overlay man- 
ager cannot read or otherwise 
handle the overlay file whose 
name was passed to OvrInit. 
Other routines in the Overlay unit 
allow the program to query the 
current size of the overlay buffer, 
increase the buffer’s size, and ask 
the overlay manager to attempt to 
load the overlay file into expand- 
ed memory. These more advanced 
routines are well-covered in the 
Turbo Pascal Owner’s Handbook, so 
I won’t discuss them here. 


Now compile! After taking all of 
these steps, simply compile the en- 
tire program to disk. You may 
want to use the Compile/Build 
command to make sure that all 
units are recompiled. The compil- 


Navigation, Combat, Repair, Survey; 


{$0 GameInit} 
{$O Navigation} 
{$0 Combat} 
{$0 Repair} 
{$0 Survey} 


var 
GameState : States; 

procedure SetupOver lays; 

begin 
OvrInit('SHIP.OVR'); 
if OvrResult <> 0 then begin 


{ type defined in MainLib } 


Writeln('Overlay error: ',GvrResult); 


Halt(1) 
end 
end; { of proc SetupOverlays } 
begin 
SetupOver lays; 
Initialize; € 
repeat 
case GameState of 
atHelm : DoNavigation; ¢€ 
inCockpit  : DoCombat; { 
inPanels : DoRepair; € 
atStation  : DoSurvey { 
end 
until GameState = endGame; 
SaveGame € 


end. { of prog Ship } 


in GameInit } 


in Navigation } 
in Combat } 
in Repair } 
in Survey } 


in GameInit } 


Figure 1: The skeleton of a starship simulation game, which places each of the 
several distinct functions of starship operation into a separate overlay. 
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er’s output (as mentioned earlier) 
consists of two files: an .EXE file, 
which contains the main program, 
the overlay manager, and all non- 
overlaid units; and an .OVR file, 
which contains the code for the 
overlaid units. 


STARSHIP SIMULATION—AN 
EXAMPLE 


Obviously, I don’t have enough 
space here to list an actual pro- 
gram that is large enough to re- 
quire overlays, but I can show you 
a (somewhat contrived) example. 

Suppose you want to write a 
starship simulation to handle four 
major functions: navigation, com- 
bat, repair, and surveying. Since 
each function is independent of 
the others, your program can use 
four major overlays. In addition, 
the code that initializes the entire 
simulation and cleans things up 
afterwards might make a fifth 
overlay. 

Figure 1 shows how the main 
body of such a program might 
look. This program uses the 
Graph unit, as well as the user- 
defined (and nonoverlaid) unit 
MainLib, which contains any 
global types, variables, and sub- 
programs. 

When the main program exe- 
cutes, it first calls the local routine 
SetupOverlays. This procedure 
then calls OvrInit, and passes 
OverInit the name of the overlay 
file, SHIP.OVR. If an error occurs, 
the entire program halts with an 
error message. 

The Initialize procedure is 
stored in the Gamelnit overlay 
unit. When Initialize is called, the 
Gamelnit unit is loaded into the 
overlay buffer. The program then 
enters a loop and calls a proce- 
dure in one of the other four 
overlay units; the current value of 
GameState determines which pro- 
cedure is called. When a proce- 
dure is called, its unit is loaded 
into the overlay buffer, and any 
unit that is currently residing 
there is overwritten. When the 
game is finished, the GamelInit 
overlay is loaded again so that 
SaveGame can be called. 


continued on page 46 
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Visual marking of blocks 
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Line, stream and column blocks Yes 
Automatic file save 
Online help 


Choice of keystroke commands or 
menu system 


Function Key assignments labeled 
‘on screen (may be disabled) Yes 


Word processing functions 


Pe |e |e 


Menu 
Yes Available 


Extensive 


~< 
oO 
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Extensive | Limited 


Complete DOS shell Yes 


_ Pop-up Programmer's Calculator and 
ASU Table : Yes 


Unlimited ‘Off the Cuff’ 
keystroke macros og 


Allocates all available memory to 
compiler when run from within | 


Intelligent indenting, template editing 

and brace/parenthesis/block 

matching and checking for C, 

PASCAL, BASIC and MODULA-2 C Only Limited 


Fexible condensed mode display Ce [| 
Pate L soo |e | sso | 66 | Hit 2 


Sauce on 
Cuff often 


To Order, Call 24 hours a day: 
1-800-221-9280 Ext. 951 


American 
Cybernetics 
1228 N. Stadem Dr. 


In Arizona: 1-602-968-1945 
Credit Card and COD orders accepted. Tempe, AZ 85281 


Requires IBM/PC/XT/AT/PS2 or full compatible, 256K RAM, PC/MS-DOS 2.0 or later. 
Multi-Edit and American Cybernetics are trademarks of American Cybernetics. BRIEF 
is a trademark of Underware, Inc. Norton Editor is a trademark of Peter Norton 
Computing, Inc. Vedit is a registered trademark of CompuView Products Inc. Copy- 
right 1987 by American Cybernetics 


PIZZA 


With EVERYTHING! 


=* Is your editor OUT TO LUNCH? 
= + Does it handle ALL OF YOUR NEEDS? 


* Is it flexible, programmable and reconfigurable? 
* MOST IMPORTANTLY, is it EASY TO USE? 


OR WOULD YOU RATHER BE EATING PIZZA? 


Fully automatic Windowing and Virtual Memory 
Edit multiple files regardless of physical memory size 
Easy cut-and-past between files 
View different parts of the same file 


Powerful, EASY-TO-READ high-level macro language 
Standard language syntax 
Full access to ALL Editor functions 


Language-specific macros for C, PASCAL, BASIC 
and MODULA-2 
Smart Indenting 
Smart brace/parenthesis/block checking 
Template editing 
More languages on the way 


Terrific word-processing features for all your 
documentation needs 
Intelligent word-wrap 
Automatic pagination 
Full print formatting with justification, bold type, underlining 
and centering 
Flexible line drawing 
Even a table of contents generator 


Compile within the editor 
Automatically positions cursor at errors 
Allocates all available memory to compiler 


Complete DOS Shell. 
Scrollable directory listing 
Copy, Delete and Load multiple files with one command 
Background file printing 


Regular expression search and translate 

Condensed Mode display, for easy viewing of your 
program structure 

Pop-up FULL-FUNCTION Programmer's Calculator 
and ASCII chart 


and MOST IMPORTANT, 
the BEST USER-INTERFACE ON THE MARKET! 
/ Extensive context-sensitive help 


KO PRE: Choice of full menu system or logical function key layout 


Function keys are always labeled on screen 

(no guessing required!) 
Keyboard may be easily reconfigured and re-labeled 
Extensive mouse support 
Easy, automatic recording and playback of keystrokes 
Anchovies easily removed 


MULTI-EDIT COMBINES POWER WITH 
EASE OF USE LIKE NO OTHER EDITOR 
ON THE MARKET TODAY. 


Aus power to your Turbo language pro- 
grams with the Borland Turbo Toolboxes. 
They provide you with source code and 
routines to be added into your programs 
$0 you don’t have to reinvent the wheel. 
And you don't pay royalties on your own 
compiled programs that include the Tool- 
boxes’ routines. 


TURBO C° 


TURBO C 2.0 RUNTIME LIBRARY 
SOURCE CODE 

An indispensible tool for serious Turbo C 
programmers! The Runtime Library Source 
Code lets you get even more out of Turbo 
C’s flexibility and control, with a library of 
more than 350 functions you can custom- 
ize or use as is in your Turbo C programs. 
You get the source for the standard C 
library, math library and batch files to help 
with recompiling and rebuilding the 


libraries.* 


TURBO PASCAL* 


TURBO PASCAL 5.0 RUNTIME 
LIBRARY SOURCE CODE 

Modify the runtime library source code or 
use it as is. You get the assembly language 
and Pascal source to the System, Dos, Crt, 
Printer, and Turbo3 units. Comes with a 
batch file to help with recompiling and 
rebuilding TURBO.TPL.* 


TURBO PASCAL DATABASE 
TOOLBOX 


With the Turbo Pascal Database Toolbox 
you can build your own powerful, pro- 
fessional-quality database programs. 
Included is a free sample database with 
source code and two powerful problem- 
solving modules. 

Turbo Access™ quickly locates, inserts, 
or deletes records in a database using B+ 
trees—the fastest method for finding and 
retrieving database information. 

Turbo Sort™ uses the Quicksort method 
to sort data on single items or on multiple 
keys. Features virtual memory management 
for sorting large data files. 


All Borland products are trademarks or registered trademarks of Borland international, inc. 
Other brand and product names are trademarks of their respective holders. Copyright ©1988 
Borland International, Inc. Bi 12802C 
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TURN UP THE POWER. . . 


TURBO PASCAL NUMERICAL 
METHODS TOOLBOX 


Turbo Pascal Numerical Methods Toolbox 
implements the latest high-level mathemat- 
ical methods to solve common scientific 
and engineering problems. Fast. Every time 
you need to calculate an integral, work with 
Fourier Transforms, or incorporate any of 
the classical numerical analysis tools into 
your programs, you don’t have to reinvent 
the wheel. It’s a complete collection of 
Turbo Pascal routines and programs that 
gives you applied state-of-the-art math 
tools. Includes two graphics demo pro- 
grams to give you the picture along with 
the numbers. Comes with complete 

source code. 


TURBO PASCAL TUTOR 


Turbo Pascal Tutor is everything you need 
to start programming in Turbo Pascal. It 
consists of a manual that takes you from 
the basics up to the most advanced tricks, 
and a disk containing sample programs as 
well as learning exercises. 


It comes with thousands of lines of com- 
mented source code on disk, ready for you 
to compile and run. Files include all the 
sample programs from the manual as well 
as several advanced examples dealing with 
window management, binary trees, and 
real-time animation. 


System requirements: All Turbo Toolboxes for the IBM PS/2™ and 
the IBM® family of personal computers and all 100% compatibles. 
PC-DOS (MS-DOS®) 2.0 or later. Turbo C Runtime Library Source 
Code requires Turbo C 1.5 or later. Turbo Pascal Toolboxes require 
Turbo Pascal 4.0 or later and 256K RAM. Turbo Prolog Toolbox 
requires Turbo Prolog 1.1 or later and 384K RAM. Turbo Basic 
Toolboxes require Turbo Basic 1.0 or later and 640K RAM. 


“Does not include source for graphics or floating point emulator. 
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TURBO PASCAL EDITOR TOOLBOX 


Turbo Pascal Editor Toolbox gives you 
three different text editors. You get the 
code, the manual, and the know-how. We 
provide all the editing routines. You plug in 
the features you want. 

MicroStar™: A full-blown text editor with 
a complete pull-down menu user interface. 
FirstEd™: A complete editor equipped 
with block commands, windows, and 
memory-mapped screen routines. 

Binary Editor: Written in assembly lan- 
guage, a 13K “black box” that you can 
easily incorporate into your programs. 


TURBO PASCAL GRAPHIX 
TOOLBOX 


Turbo Pascal Graphix Toolbox is a collec- 
tion of tools that will get you right into the 
fascinating world of high-resolution mono- 
chrome business graphics, including gra- 
phics window management. Draw both 
simple and complex graphics. Store and 
restore graphic images to and from disk. 


TURBO PASCAL GAMEWORKS 
Explore the world of state-of-the-art com- 
puter games with Turbo Pascal Game- 
Works. Using easy-to-understand example 
games, it teaches you theory and tech- 
niques to quickly create your own com- 
puter games. Comes with three ready-to- 
play games: Turbo Chess,” Turbo Bridge,” 
Turbo Go-Moku.” 


WITH TURBO TOOLBOXES! 
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TURBO PROLOG* 


TURBO PROLOG TOOLBOX IS 
SIX TOOLBOXES IN ONE 


More than 80 tools and 8,000 lines of 
source code help you build your own 
Turbo Prolog applications. Includes tool- 
boxes for menus, screen and report 
layouts, business graphics, communica- 
tions, file-transfer capabilities, parser 
generators, and more! 


TURBO BASIC* 


TURBO BASIC DATABASE TOOLBOX 
With the Turbo Basic Database Toolbox you 
can build your own powerful, professional- 
quality database programs. Includes 
Trainer, a demonstration program that gra- 
phically displays how B+ trees work and a 
free sample database with source code. 
The Toolbox enhances your programming 
with 2 problem-solving modules: 

Turbo Access quickly locates, inserts, or 
deletes records in a database using B+ 
trees—the fastest method for finding and 
retrieving database information. 

Turbo Sort uses the Quicksort method to 
sort data on single items or on multiple 
keys. 


TURBO BASIC* EDITOR TOOLBOX 


Turbo Basic Editor Toolbox will help you 
build your own superfast editor to incorpo- 
rate into your Turbo Basic programs. We 
provide all the editing routines. You plug in 
the features you want! We've included two 
sample editors with complete source code. 


MicroStar: A full-blown text editor with a To order, call 
pull-down menu user interface and all the (800) 543-7543 
standard features you'd expect in any word 

processor. ~~ 
FirstEd: A complete editor with windows, zy 
block commands, and memory-mapped 

screen routines, all ready to include in 

your programs. BORLAND 


YES! | want the Borland Turbo Toolboxes® indicated below! 


To order, simply complete this coupon, or call (800) 543-7543 and have your credit card number and the 
code ATIO ready to give to the operator. Mail coupon to: Borland International, 1800 Green Hills Road, P.O. 
Box 660001, Scotts Valley, CA 95066-0001 


O Turbo C Runtime Library 

DO Turbo Pascal Runtime Library 

0 Turbo Pascal Gameworks 

O Turbo Pascal Tutor 

0 Turbo Pascal Editor Toolbox 

© Turbo Pascal Numerical Methods Toolbox 


O Turbo Pascal Database Toolbox 
O Turbo Pascal Graphix Toolbox 
OD Turbo Prolog Toolbox 

0 Turbo Basic Editor Toolbox 

OO Turbo Basic Database Toolbox 


Turbo C and Turbo Pascal Runtime Libraries each $150 pO \ an seat nipe eae MS 
Toolboxes $99.95 each x Qty. ae ht 
CA and MA residents add appropriate sales tax 9 .__ 

Shipping —___ 


Total 
Diskette size: 0 5%" 0 3%" 


Payment: O Visa 0 MC OO Check 0 Money Order 
Name 

Shipping Address 

City, State, Zip 


Phone 


Credit Card # 


Expiration Date / 


Oulside U.S. make payment by bank draft payable in U.S. dollars drawn on a U.S. bank. CODs and purchase orders will not be accepted. 


Overlays can be a great help 
when debugging very large pro- 
grams. If kept fully intact, such 
programs may be too big to run in 
memory under Turbo Pascal. By 
breaking a very large program 
into overlays, the program may be 
made small enough to run under 
the Integrated Environment— 
which places the services of the 
Integrated Debugger at your 
disposal. 


REMEMBER 


A number of things should be 
kept in mind when using overlays. 
First, make sure that OvrInit is 
called before calls are made to 
any of the routines in overlay 


OVERLAYS WITH 5.0 
continued from page 42 


DEBUGGING SUPPORT 


The Turbo Pascal 5.0 Integrated 
Debugger fully supports overlays. 
You can single-step through calls 
to routines in overlay units, and 
those units will be loaded into and 
out of memory as needed. Again, 
this process is handled automat- 
ically and invisibly (except, of 
course, for the disk access that oc- 
curs as units are loaded into mem- 
ory). You can set breakpoints 
within overlay units, use the Call 
Stack and Find Functions com- 
mands, and otherwise treat these 
units just like nonoverlaid units. 


Write Better 


Turbo 4.0 Programs... 
Or Your Money Back 


You'll write better Turbo Pascal 4.0 programs easier and faster 
using the powerful analytical tools of Turbo Analyst 4.0. 
You get * Pascal Formatter * Cross Referencer * Program 
Indexer * Program Lister * Execution Profiler, 
and more. Includes complete source code. 

Turbo Analyst 4.0 is the successor to the 
acclaimed TurboPower Utilities: 
“Ifyou own Turbo Pascal you should own the Turbo 
Power Programmers Utilities, that’s all there is to it?” 

Bruce Webster, BYTE Magazine, Feb. 1986 


Turbo Analyst 4.0 is only $75. 


A Library of Essential Routines 
Turbo Professional 4.0 is a library of more than 400 state-of-the-art 
routines optimized for Turbo Pascal 4.0. It includes complete 
source code, comprehensive documentation, and demo 
) programs that are powerful and useful. Includes 
|} * TSR management * Menu, window, and data 
/ entry routines * BCD ° Large arrays, and more. 


Turbo Professional 4.0 is only $99. 
Call toll-free for credit card orders. 
1-800-538-8157 ext. 830 (1-800-672-3470 ext. 830 in CA) 


Satisfaction guaranteed or your money back within 30 days. 


TurboPower Software 
P. O. Box 66747 
Scotts Valley, CA 95066-0747 


Fast Response Series: 

= T-DebugPLUS 4.0—Symbolic 
run-time debugger for Turbo 4.0, 
only $45. ($90 with source code) 

@ Overlay Manager 4.0—Use over- 
lays and chain in Turbo 4.0, only $45. 
Call for upgrade information. 


Turbo Pascal 4.0 is required. 
Owners of TurboPower Utilities w/o u 
source may upgrade for $40, w/source, 
$25. Include your serial number. For 
other information call 408-438-8608. 
Shipping & taxes prepaid in U.S. & 
Canada. Elsewhere add $12 per item. 
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units. To be safe, call OvrInit 
either at the start of the main 
body of the program, or (as de- 
scribed below) in the initialization 
code of a nonoverlaid unit. 

Avoid having initialization code 
in the overlay units. If such code 
is necessary, then ensure that 
OvrInit has been called before 
those units are initialized. The 
only way to do this is to put the 
call to OvrInit into the initializa- 
tion section of a nonoverlaid unit 
that appears in the USES clause 
prior to any overlaid unit. 

Be sure to call OvrInit before 
anything is allocated on the heap. 
Unless the heap is completely un- 
touched, OvrInit won't function 
correctly when called. 

Make sure that Overlay appears 
in the USES clause before any of 
the overlaid units. The safest 
solution is to put Overlay first. 

Also, make sure that all units, as 
well as the main program, are 
compiled with the {$F+} directive 
present, or (equivalently) with the 
Options/Compiler/Force far calls 
toggle set to On. 

Finally, the DOS unit is the only 
one of the standard units shipped 
with Turbo Pascal that may be 
overlaid—and putting DOS out as 
an overlay is not a good idea. Any 
of your own units that contains in- 
terrupt handlers also may not be 
overlaid. 


CONQUER SPACE 

In order to write good programs, 
the needs of the program specifi- 
cation must be balanced against 


| available DOS memory, expanded 


memory, and disk storage re- 
sources. The size of Turbo Pascal 
4.0 programs is limited to avail- 
able DOS memory space. Turbo 
Pascal 5.0’s overlays feature raises 
that size limit well beyond the 
megabyte point. How far you can 
take the size of a single program 
depends upon how efficiently you 
use data space and symbol table 
space. With some care in design, 
your programs can (in most cases) 
be as large as they need to be. @ 


Bruce Webster is a computer merce- 
nary living in California. He can be 
reached via MCI MAIL (as Bruce 
Webster) or on BIX (as bwebster). 
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C CODE FOR THE PC 


source code, of course 


MS-DOS File Compatibility Package (create, read, & write MS-DOS file systems on non-MS-DOS computers) ........ $500 
Bluestreak Plus Communications (two ports, programmer's interface, terminalemulation) ............2.4. $400 
PforC or PforCe+ + (COM, database, windows, file, user interface, DOS & CRT) OE lettin Bia. Sw she wea ee 
COE Query System: (SOL retrievals'plus Windows), 4.0 9 us ss ot st! as lee Gh te es oe kh a we ce, Be Be) 
GraphiC 4.1 (high-resolution, DISSPLA-style scientific plots in color & hardcopy) ....-- 1 see eee eee =i, eee 
Barcode Generator (specify Code 39 (alphanumeric), Interleaved 2 0f S(numeric),or UPC) ............ ris ois! OU 
Vmen/C (virtual memory manager; least-recently used pager; dynamic expansion of swapfile) ............06. $250 
PC Curses (Aspen, Software, System V compatible, extensive documentation)... 2... 6. ee ee eee eee J te: 41, ee 
Greenleaf Data Windows (windows, menus, data entry, interactive form design). . . 2. 2 2 ee ee ee ee ee ee $220 
Vitara WIDOWS Yet coon Ge ke, comtciten a: emia od eeverton Soucuay Shia ssyeeies, Sainte yyn all an ae) Su ce om. Sots ap eas 200 
Greenleaf Communications Library (interrupt mode, modem control, XON-XOFF) ...........+24. $175 
Turbolex (TRIP cecibed HP. PS dotdriverss GM fontesLades) 3.2 a6 2 elle sw ce 6 ees 6 we ol $170 
Essential resident: C (USRify C programs, DOS'shared libraries). @ ce ee ee et ee $165 
Greenleat Functions (296 useflul'C fimotions; all DOS services)! 3 a si we a eS ee ss ls se te $160 
Bssentiahe Utility hibrary.(400 usetul RMCuONS) fi. 2 als is Ge Ras es ew Ses eee te Se ae Ss EO 
Essential Communications Library (C functions for RS-232-based communication systems)... . 2... ee ee ee eee $160 
WKS Library Version 2.0 (C program interface to Lotus 1-2-3, dBase, Supercalc 4, Quatro, & Clipper) ......... 2 2) eles 
OS/88 (U ++x-like operating system, many tools, cross-development from MS-DOS) ............+.+4... % a peo 
ME Version 2.0 (programmer’s editor with C-like macro language by Magma Software; Version 1.31 still$75) ......... $140 
Turbo G Graphics Library (all popular adapters, hidden line ee Wem strat we. seuke dit cackawme te SIN cue aay cote Rs eee teers $135 
PC Curses Package (full Berkeley 4.3, menu and dataentryexamples) .... 2... 1... 525s ee eee eevee Ee ey Gees 
Cities (B-Firce ISAM driver. :multiple variable-length keys)! 0 on. ee 8 ste oe so + SEIS 
Minix Operating System (U++x-like operating system,includesmanual) .. . 2... 1 1 ee ee ee eet eee og ce LOS 
PGP EMU MIRTLE AP implementauomforrCs)iies tls sos 8 2 patel AG le) Oh S de) tothe oer ey ers Pele we ips: $100 
B-lree- Library 4c ISAM Driver (filessystent utilities: by SOMfocus)) 60. 6 6s es 8 we el wn ew $100 
Ae RTONIGE (DROP RAIN GROCULION PFONIETOON: cise al as) whe a ln ag les ace ae were a eS) sles, Bla el os Is ~~. + SLOo 
Entelekon C Function Library (screen, graphics, keyboard, string, printer,etc.) . 2... 6 1 ee ee ee ee eee So,» EOLOO 
Entelekon Power Windows (menus, overlays, messages, alarms, file handling,etc.). 2... 2. ee ee ee ee ee eee $100 
TurboGeometry (library of routines for computational geometry) . . . 6 ee ee ee sie ley are 
QC88 C compiler (ASM output, small model, no longs, floats or bit fields, 80+ functionlibrary) . . .. 1... 2.222 ee eee $90 
Wendin Operating: System Constniction Kitor PCN X PCV MSiO/S Shells... ss ke Sa, ac 8s Be i lee we es $80 
C Windows Toolkit (pop-up, pull-down, spreadsheet, CGA/EGA/Hercules) . . 2 2. 6 ee ee ee te ee $80 
JATE Asynce Terminal Emulator (includes file transferand menu subsystem) . . 2... 2 ee ee ee ee ee 5 eee st. 
MultiDOS Plus (DOS-based multitasking, intertask messaging, semaphores) . . . - 2... 2 ee ee ee ee ee ee a eis fs OO 
WKS Library Version 1.03 (C program interface to Lotus 1-2-3 program & files) 2... 2 2 11 ee ee ee ee te $80 
Professional C Windows (lean & mean window and keyboard handler). . . . . 2 1 ee ee ee ee ee ee es Sis a eee 
Ip: (exible ornter driver, most populanprinters suppagedyr + ny Gos) ats! Gls wt ewes © we 6 ws ie es Comite: 
Quincyfinteractive Cinterpreteryins. css. iets nturensiaei ah ces 8) ia) ef Savers, We aya calle, Gouiew ie ge eee ee Sw a tec oe 8258) 
EZ2ASM (assembly. languave macros bridging: Cand MASM)) i 2 so Sei ek ee ee ee Se $60 
PURGE (parse ee ANAC RMENE) bu peas tl bo Pee a Mad purl sil 4 eee) Al abhi mo mae Meudor ewe Gives 32 ¥ 5 + eS & es $60 
MiceoF im ioo1kit (2a nixesque utilities fortMS-DOS) nu wa eG wes es ee ew se ew - $50 
XT BIOS Kit (roll your own BIOS with this complete set of basicinput/output functions forXTs) .......-.... & o) Se SSO 
HELE (ponalp dcp SYStCDE OUUGCE) Nc csiaty sso Wainy Giaeuiciisl ts cule Wallcaritemie i, ja) le) el Ue) Ie "a (Sao) i, 5) 2) uum Ia ay i ik Ge tape. 
Multi-User BBS (chat, mail, menus, sysop displays; uses Galacticomm modem card)... . 2... 1 ee eee eee «ik 3) o OO 
Make (macros alulaneuapes, Oiitcimnules): eo cea isuiee sd, Me wel oy es We Se 9 fo) HS. age ttl | ROMION ONG) Ww, 3) =) sips sues $50 
Vector-to-Raster Conversion (stroke letters & Tektronix 4010 codes to bitmaps)... 2... 1 ee ee ee ee ee $50 
Coder’s Prolog (inference engine for use with C programs) On aT a CRT TE Oe Gc OMe oo OG $45 
Virtual’ Memory Systeny (least te ceniy seu SWADDINE)| Ue 6 es al whale e's ee 5 Wa ole SOs 6 2 Re 4 $40 
G-Notes (pop-up hein itor'€ prosramimers:..., aug YOUR OWN NOLES) is. sic ss, ecw) SIs oe 2 Fo el ine fee we) ese $40 
Biggerstaii’s System tools (qnulii-tasking WinGOWwManegerKit): <2 4 8 es ee ee ee Sw ls wf ge he 8 a $40 
PC-XINU (Comers nmr operal pr avslem tor atic cule le sieves: is) is: ce. jellies Wo. cs, Mal Sod ete «ih Touts Manns © 08 ad does, tae $35 
CILIE'S (rule-based texperusyatc Hu SCheraton sWersiGm G2) 1) fe dauke sw) ia) al ts) Soe) ie cx) ve be ts) << COS qe) ent $35 
‘Tiny Curses (Berkeleyvcurses nackte angen say siren ie MOR lo) 7 Nea epee eee? Ql 2 vey S Pegeeet See aS) bs) il de $35 
TELE Kemel or TELE Windows (Ken Berry's multi-tasking kernel & window package) . .....-- 2-22-22. $30 
SP (pelling:checker with dictionary and: maintenance tools) ee a se ee le ie ah ene ee ess sn ne ew ee $30 
Clisp Gisp interpreter with extepsiveintemals: documentation}. <6 ee ke le we ee “4 2 gee 
Translate Rules to C (YACC-like function generator for rule-based systems) . . 2. 2 1 6 ee ee ee ee ee ee $30 
6-Pack of Editors (sxc public domaineditors for use;study Snacking) «6 cos ee ek ew ee kw $30 
Gninel Pack) (i4iiie con pression a expansion PYOCLaMS) es sw ow Ge eke es ee ee $30 
ICONG CString guest PLocensin gan piawer MOISION Gil sn ieukcd opts. oe ac an ee" ae Sy SA agile PEE wa a) a) su 6 Peo feneee are $25 
BEEN ash lexical analyzer ceneralor, Mewsitiproved WEN) 6 50 oe as ke a He 4 Bl ele ws so we we wn Ge $25 
aoe (lexical analyercenerator, Am Giae DUCAIPOOGIC) Macecite rea) cx i iia ROE fe See HTS Gigs oS lke aI eee $25 
Bison & PREP (YACC workalike parser generator & attribute grammar preprocessor). . . . - . . . eee ee ee ee ee $25 
AutoTrace Py LrACer Ang Me MOLY Uasner CALCRER) Greet ne ws ic CN bas a) ao ey ey Gh ek ellente: es) s Tl Gl ee $25 
Arraysior G(pacro packaveto case HANGIN OLAIGVS)\« «leeds 2 em 6 so Gone = =) 8) «) ol We pe) Ws 9) ee we $25 
GOPS (collection of handy C-++-- classes'by Keith'Gorlen of NIH) . 2. 2 5 bs ee ee ee ee $20 
© Compiler Torture Test (checks a C’compileragainsth ch RR) ane 6 ee a ee se $20 
Benchmark Package (C compiler, PC hardware, and Unixisystem) . . 5 5 2 2 eee te te te te et tw et ws $20 
T™N3270 (remote login to IBM VM/CMS as a 3270 terminal on a 3274 controller) . . 6. 6 ee ee ee et ee ee ee $20 
PAGrHCOSUUO SLOSS SaRoe DIED mene Mercia eats MOC eG) nel altel arch Sobel Saled wists: os MeMiell'c, Sl csiye nom sua We $20 
Laist-Pac (© functions forists; Stacks ANG QUEUES) cae 7.6. i lo 8 yet oy AS spre ah ale | igyie! iw 1H feb ie Sy oy aes $20 
ALT Macro!Processor (general purpose text‘transiator)) . . 5 ew ee a Fe te a ee ee es ce nse 
Gireativity. (eliza based NOletaker)) ics cine cots Cue aiu coin mine cle % GPM =) Umea iy eo + alles kod isles Ue women eee $15 
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BUG HUNTING, 
BORLAND STYLE 


Jeff Duntemann 


ack in 1976, I wire-wrapped a 

computer that was based on a cir- 

cuit diagram in Popular Electronics. 

My new computer used the 
CDP1802 CPU, which had a single-line se- 
rial output that could be set to one or to 
zero; I connected the line to an LED. A sin- 
gle instruction brought the line high, and 
another instruction brought it low again. In- 
put to the machine was a row of eight toggle 
switches; output was a two-digit hexadecimal 
display. To test the machine, I toggled in the 
single-byte opcode that should have turned 
the LED on by bringing the serial line high. 
Nothing happened. I triple-checked the op- 
code (but seriously, how many ways are 
there to toggle in 7BH?) The hex display 
read 7B. The toggle switches were set to 
0111 1011. The LED stayed off. 

I assumed the CPU was bad, until I 
swapped it into a friend’s similar machine 
and found out that my CPU worked fine. I 
swapped all the ICs. I checked all the wir- 
ing. The machine appeared to be in perfect 
condition—yet it wouldn’t run a one-byte 
program. Time and lots of Mountain Dew 
uncovered the following problems: 


1. By mistake, I had wired the toggle 
switches upside down; in other words, a 
switch whose bat handle was high (indi- 
cating a binary 1) was actually putting out 
a binary 0. 

2. By mistake, I had socketed an octal inver- 
ter, rather than an octal driver, between 
the toggle switches and the hex display. 
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What this means is that the toggle 
switches were putting out an inverted byte, 
but that the inverting drivers that fed the 
hex display reinverted the inverted byte 
from the toggle switches, making the byte 
look normal again. The switches said 7BH. 
The displays said 7BH. But the machine 
was actually receiving an 84H byte, which 
did something harmless but incorrect. It was 
an accidental but diabolical partnership be- 
tween two otherwise obvious screwups that 
hid one another perfectly for several weeks. 

We don’t wire-wrap our machines any- 
more, thank God, so hardware bugs like this 
have pretty much become extinct. But bugs 
will always be with us, and my 1976 expe- 
rience says something absolutely basic 
about debugging: Inspection is not enough. 
You can fix some bugs by staring at your 
code after a good night’s sleep. You can fix 
a few more by pulling procedures out of a 
program piecemeal and plugging them into 
proven programs to get a second opinion. 
But even when all of the parts check out 
separately, the little devils often refuse to 
cooperate in peculiar ways when reassem- 
bled, no matter how carefully. 


LIFTING THE LID 


There’s no way around it: You have to lift 
the lid, go in there, and see what’s happen- 
ing. Assume nothing. Watch every statement 
execute. Look at every variable at every step 
of the way. If you fail to do this, you’ll miss 
something, and the something you'll miss 
will be the one thing you’ve been looking 
for for weeks. 


The process of opening up the closed universe of 
a computer program for examination requires spe- 
cial tools. We call these tools debuggers, and commer- 
cial software development would be impossible with- 
out them. How debuggers work is the blackest of 
black arts, but what they do falls into two broad 
categories: 


1. Debuggers stop and start program execution on 
command without losing the current state of the 
program. A program can be paused at a preset 
point in the code (called a breakpoint), or it can be 
made to pause after each program step. (This pro- 
cess is called single-stepping or tracing.) Tracing a 
program allows you to see “what it’s doing in 
there.” Breakpoints offer a chance to examine the 
effects of the program statements on program 
variables in medias res. 


2. Debuggers let us examine and change the values 
of program data items. At the lowest level, this in- 
cludes CPU registers, memory, and I/O ports. 
Some advanced debuggers (called symbolic debug- 
gers) have the ability to relate memory, and occa- 
sionally machine registers, to program identifiers 
such as variable names. 


POINTS OF VIEW 


Even with respect to the way that they execute those 
two missions, debuggers are a pretty diverse lot. Ev- 
ery debugger falls into one of three categories that 
turn on the way the debugger (and, hence, you the 
programmer) view the program under examination. 
This matter of point of view is critical. There are two 
points of view from which to examine a computer 
program: the machine’s point of view, and the pro- 
grammer’s point of view. 


The machine sees the program as a series of ex- 
ecutable binary instructions in memory, which are 
located alongside other memory locations that are 
set aside to store binary data. The machine’s view 
also includes a set of values in machine registers that 
continually change as the program executes. In ad- 
dition, there may be I/O ports that transfer data to 
and from the outside world. 

Since the invention of high-level languages, such 
as C and Pascal, the programmer has had quite a dif- 
ferent view of a program. A high-level language 
groups incomprehensible machine instructions to- 
gether into higher-level program statements that are 
more easily read, remembered, and understood. The 
language also partitions data storage memory into 
named chunks that reflect familiar concepts in the 
human culture: yes/no answers, numbers, charac- 
ters, values that are grouped into indexed arrays or 
named records, and so forth. The state of machine 
registers is usually hidden from the programmer’s 
view, except in rare circumstances. 

You can think of a program as a structure printed 
on a piece of paper that is suspended in space be- 
tween the programmer (above) and the machine 
(below). To the programmer, who looks down on the 
program from above, the structure appears to be 
made up of program statements and named vari- 
ables. The machine, which looks up at the program 
from below, sees a conglomeration of memory loca- 
tions that contain either machine instructions or bi- 


continued on page 50 
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nary data, plus a scattering of ever-changing regis- 
ters. Two different views of exactly the same pro- 
gram. 

Debuggers are classified based upon whose view 
they take. High-level debuggers look over the pro- 
grammer’s shoulder, and understand and display 
program statements and variables. They cannot dis- 
play memory locations, machine instructions, or ma- 
chine registers. Low-level debuggers can step through 
machine instructions and display blocks of memory. 
However, these dubuggers are ignorant of high-level 
languages, and have no knowledge of program state- 
ments or variables. Full symbolic debuggers sit on the 
fence between the two worlds, embracing both of 
them. On the one hand, these debuggers understand 
high-level languages—they can step through a C or 
Pascal program line by line, displaying the contents 
of program variables as they go. On the other hand, 
full symbolic debuggers can also show the machine’s 
view of memory, instruction opcodes, and machine 
registers. Best of all, these debuggers can show the 
synergy between the two views of a program—vari- 
ables that are loaded into machine registers; pro- 
gram statements that display beside their equivalent 
machine instructions; and data that moves among 
variables, registers, and I/O ports. 

The classic low-level debugger is DOS DEBUG, 
which is included with every copy of DOS. Inter- 
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preted BASICA, with its TRON and TROFF state- 
ments and BREAK/CONTINUE feature, is part 
high-level debugger. Full symbolic debuggers include 
SYMDEB, Periscope, and CodeView. 

Up until now, the Borland line has been missing 
an entry in the important category of debugging. But 
now, as the cover theme of this issue of TURBO 
TECHNIX indicates, we’re introducing three differ- 
ent debuggers that capably fill the vacuum. 


INTEGRATED DEBUGGING 


Both Turbo Pascal 5.0 and Turbo C 2.0 contain high- 
level debuggers that are intimately intertwined with 
both languages’ Interactive Development Environ- 
ments. We call these new debuggers the Borland In- 
tegrated Debuggers, because they’re always beside the 
compiler, ready to go, while you’re putting your pro- 
grams together. I offer a close look at Turbo Pascal 
5.0’s Integrated Debugger on page 12 of this issue; 
Kent Porter leads a tour through Turbo C 2.0 and its 
Integrated Debugger on page 62. 

The Borland Integrated Debuggers handle most 
program development, especially with respect to 
small programs and programs that don’t perform a 
lot of black magic. On the other hand, the larger 
and the more ambitious your programs become, the 
greater the chances that you'll concoct a bug that is 
beyond the grasp of the Integrated Debuggers. The 
pursuit of system-level code crickets requires the 
synergy of a full symbolic debugger—and now you 
can turn to Turbo Debugger. (If that won’t find ’em, 
you'd better go have a look at your toggle switches.) 
Michael Abrash shows you around the multi-win- 
dowed mechanisms of Turbo Debugger on page 52 
of this issue. 

Turbo Pascal 5.0 contains a few other surprises as 
well. Overlays are back, as Bruce Webster describes 
on page 38. Procedural types (long a part of Modula 
2) are now part of Turbo Pascal, and Neil Rubenking 
uses them to create a generalized file search engine 
on page 27. Turbo C’s floating point support has 
seen a few enhancements, as Roger Schlafly points 
out on page 67 in the sequel to his January/Febru- 
ary, 1988 cover article, “Floating Point in Turbo C.” 

Finally, Borland has released Turbo Assembler as 
a companion product that ships with Turbo Debug- 
ger. While retaining full compatibility with MASM 
5.x, Turbo Assembler also offers Ideal mode, which 
is anew and more comprehensible syntax for assem- 
bly language, plus 286/386 support. Tom Swan intro- 
duces Turbo Assembler’s features, including the new 
Ideal mode syntax, on page 120. 

The more power you have, the more ways there 
are to go wrong. In future issues of TURBO TECH- 
NIX, we'll pursue our ongoing mission of putting 
useful programming techniques in your hands. At 
the same time, we'll provide more information about 
fixing things that don’t work the first time out. Re- 
member: Assume nothing. Examine everything. And al- 
ways use the best tools that you can bring to bear on 
the problem. @ 
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TURBO DEBUGGER: THE VIEW 


FROM WITHIN 


Borland’s new Turbo Debugger adds unprecedented 
symbolic debugging power to Turbo C and Turbo Pascal. 


Michael Abrash 


Long ago, I made a comfortable living 
writing video games for the PC. Whenever 
I ran into a bug, I had no choice but to 
fire up DEBUG, the debugger IBM then 
provided free with DOS. DEBUG wasn’t 
ee. much of a debugger, since it had just one 
kind of breakpoint, couldn’t display data structures, 
and could only debug at the assembly language level. 
In fact, the only thing DEBUG had going for it was 
that it was better than the alternative, which was 
nothing. 

As you'll read elsewhere in this issue, Borland has 
closed the debugging gap in a big way by adding in- 
tegrated debugging to both Turbo Pascal (p. 12) and 
Turbo C (p. 48). Still, because each of the integrated 
debuggers has to squeeze into memory along with 
an editor, a compiler, a linker, and a user program, 
the integrated debuggers are inescapably less pow- 
erful than standalone debuggers. Certain debugging 
problems, such as runaway pointers, complex error 
conditions, debugging of assembler code, and the 
like, absolutely require a state-of-the-art symbolic de- 
bugger. Unfortunately, advanced debuggers tend to 
be difficult to use, and are generally more suited to 
debugging assembly language than Pascal or C pro- 
grams. The ideal debugger would not only be state- 
of-the-art in terms of sheer power, but also would be 
as easy to use for high-level languages as for 
assembler. 

Borland’s new Turbo Debugger fits that descrip- 
tion to a T. Equally at home with Turbo Pascal, Turbo 
C, or Turbo Assembler programs, Turbo Debugger 
offers an intuitive interface and a suite of debugging 
features that take software-only debugging to the lim- 
its of possibility. On 386-equipped systems, Turbo 
Debugger can put the advanced capabilities of the 
80386 CPU to work to provide limited hardware as- 
sistance in terms of hardware breakpoints. Another 
386-based debugging breakthrough allows the de- 
bugger to run in 386 protected mode and the appli- 
cation being debugged to occupy a separate virtual- 
86 partition. This means that your application can be 
as large as necessary without crowding the Debugger 


PROGRAMMER 


out of DOS memory. Furthermore, the application 
can reside at the same addresses that it will occupy 
on its target system. 

Let’s take a closer look at Turbo Debugger, and ex- 
plore the situations when you might want to step up 
to Turbo Debugger from your Turbo language’s in- 
tegrated debugging. 


ADVANCED DEBUGGING FEATURES 


At heart, there’s only one question to ask about a de- 
bugger: “How well does it let me catch error condi- 
tions in my programs?” The key to catching error 
conditions is breakpoint capability—and Turbo De- 
bugger is extremely powerful in this area. 

Breakpoint capability normally refers to the ability 
to instruct a program to stop for examination when 
a certain line of the program is reached. Turbo De- 
bugger has all of the standard breakpoint features. 
A breakpoint can be set simply by pressing the F2 
function key on the line where you want the break 
to occur, or a break address can be specified by way 
of the Breakpoints menu. A program can also be 
executed either one source code line or one assem- 
bly language instruction at a time, and can either 
step over or trace into subroutines. Alternately, you 
can just sit back and watch your PC screen change as 
Turbo Debugger runs a program line-by-line at a re- 
duced speed. You can have Turbo Debugger run to 
a certain line by pressing F4 on that line; to run 
Turbo Debugger to the end of a function, simply 
press Alt-F8. 

These are fairly standard debugger breakpoint ca- 
pabilities—and Turbo Debugger goes even further. 

Turbo Debugger lets you stop a program either 
when a memory location is changed, or when an ex- 
pression becomes true. (By the way, expressions can 
be evaluated in the notation of the language of your 
choice—Pascal, C, or assembler—at any time, and 
these expressions can even contain functions.) 
What’s more, you can select the number of times that 
a breakpoint condition must occur before it causes 
a break, so that you don’t have to wait through 100 


continued on page 54 
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THE VIEW FROM WITHIN 
continued from page 52 


iterations of a loop if the case you're interested in 
occurs during the 101st pass. Alternatively, Turbo De- 
bugger can record occurrences of a given breakpoint 
in its ongoing log; later, you can refer back to the log 
to see how the current state was reached. You can 
also record comments and data dumps into the log, 
and can record the log to disk. Perhaps most remark- 
ably, you can instruct Turbo Debugger to execute the 
expression of your choice at a given breakpoint; 
since such expressions can modify variables, this 
gives you a way to temporarily patch a line of code 
into a program without leaving—or even restarting— 
a debugging session. As I'll show later, these sophis- 
ticated data breakpoints let you catch bugs that might 
otherwise take hours to find. 

There’s a price to be paid when the more sophis- 
ticated breakpoints are used. Programs run more 
slowly when a changed memory location breakpoint 
is active, for example, since Turbo Debugger must 
stop after each line to see whether the breakpoint 
condition has been met. To speed things up, Turbo 
Debugger offers an option that combines code and 
data breakpoints. You can specify that a given data 
breakpoint should only be checked when a given 
line is executed; if you know where but not when a 
bug occurs, you can quickly reach that point with a 
combined code and data breakpoint. 

To facilitate the use of hardware breakpoints, 
Turbo Debugger contains a device-driver interface 
that allows it to work with third-party hardware de- 
bugger products from vendors such as Atron and 
Periscope. The first such Turbo Debugger-compatible 
product has already appeared, in the form of Purart’s 
Trapper board (see accompanying sidebar). A device 
driver is shipped with Turbo Debugger that allows 
the use of the 386 CPU’s built-in hardware debug- 
ging features without additional hardware. 


THE USER INTERFACE 


While breakpoints are a prominent feature of any 
debugger, the user interface makes the power of a 
debugger readily available. Turbo Debugger expands 
upon the familiar Borland windowing interface in a 
number of ways. 


Look at the context. For starters, Turbo Debugger is 
highly context-sensitive. Help is context-sensitive. 
Local variables are popped up for inspection from a 
default scope that is determined by the cursor’s loca- 
tion in the source code. The default language con- 
vention by which expressions are evaluated depends 
upon the type of source module being debugged. If 
Turbo Debugger thinks you’re looking at a string, it 
displays that data as text; otherwise, the data is dis- 
played as hex bytes. Default responses to prompts 
are based on the text located below the cursor. In 
many cases, text can be highlighted on the screen 
and then can serve as the response to a prompt; this 
saves considerable typing. 
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Open a window. Turbo Debugger’s basic screen con- 
sists of any number of windows, with pull-down 
menus on the menu bar at the top of the screen. At 
your option, windows may overlap to any degree or 
not at all. Figure 1 shows a Turbo Debugger screen 
that contains three windows and a pull-down menu. 
You can readily rearrange, resize, and move between 
the windows with either hotkeys or menu com- 
mands. Window configurations can be saved to disk 
and reloaded later. In addition, Turbo Debugger al- 
lows you to undo the last window close, so you can 
quickly recover if you close a window and then de- 
cide you need that window after all. 


Local menus. Each type of window has a specific 
purpose. There are windows for viewing source 
code, viewing the CPU state, inspecting data struc- 
tures, watching variable values, dumping memory, 
and more. Consequently, different actions are ap- 
propriate to different types of windows. Rather than 
try to cram the commands for all of the windows 
onto the single menu bar at the top of the screen, 
Borland instead chose to implement local menus. A 
local menu is a popup menu specific to the window 
that is currently active. The local menu for the cur- 
rent window can be popped up at any time by press- 
ing Alt-F10. Figure 2 shows the local menu for the 
module viewer window. 


Hotkeys and other tricks. As usual, Borland has pro- 
vided hotkeys as a quick way to select many menu 
items. To help you remember the many hotkeys, the 
bottom line of the screen (known as the help line) 
shows the available hotkeys at any given time. If you 
hold the Alt key down, the help line shows the Alt 
hotkeys. Hold down the Ctrl key, and the Ctrl hot- 
keys are displayed. The Ctrl hotkeys are also hotkeys 
into the current local menu, so holding down Ctrl is 
a good way to see the local menu commands that are 
available at any time. 

The Turbo Debugger interface provides other 
handy features. For instance, it maintains history lists 
of your responses to prompts. When a given prompt 
is issued, your recent choices are displayed as well; 
you can save considerable typing by reusing or mod- 
ifying one of your earlier choices. 

As another convenience, whenever Turbo De- 
bugger presents an alphabetized list (such as the list 
of global variables in the variables viewer window), 
you can start typing the name of any item in that list. 
As you press each key, Turbo Debugger instantly dis- 
plays the next item in the list that matches the key- 
strokes you’ve entered so far. This is quite handy if 
you use hundreds of variables and can’t remember 
all of the letters in a given variable. 


THE VIEW FROM WITHIN 


As you can see, Turbo Debugger’s user interface is 
designed to let you work as efficiently as possible— 
but what does it actually let you do? Briefly put, the 
interface offers very flexible ways to view and modify 
code and data within an executing program. 


struct TextBlock *NextTextBlock: /* p 
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Figure 1. Turbo Debugger’s window- 
ing user interface. Each function oc- 
cupies a separate window. The win- 
dows may overlap or not, as desired. 


Figure 2. The local menu of a module 
viewer window. 
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Pick a level. You can view code at either the source 
code or assembly language level. If you view code at 
the source code level (in a module viewer window), 
you don’t need to see individual instructions, regis- 
ters, or flags unless you want to. At this level, code 
can be single-stepped a source-level statement at a 
time. If you view code at the assembly language level 
(in a CPU viewer window), you can see every detail of 
the program as it executes. Here, code can be single- 
stepped an instruction at a time. As an alternative to 
viewing code with either method individually, both 
module and CPU viewer windows can be displayed 
simultaneously so that you can watch code execute 
at both levels. 


Any or all of the source modules in a program can 
be viewed at any time. You can search the source 
code for a text string, just as you would search for a 
text string in a text editor. 


Follow the trail. The stack viewer window shows the 
function calling trail that led to your current location 
in the program. You can move to any function in the 
stack viewer window and see that function’s local 
variables and actual parameters. 

Code can be assembled directly into the program 
for patching purposes, although those changes are 
only made to the program in memory. Such changes 
are lost as soon as the debugging session is ended, 
or the program is reloaded. 


continued on page 56 
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Show me your data. Now we come to viewing data. 
The dump viewer window lets you display any area of 
memory in hex and ASCII. You can specify the area 
of memory to dump with any expression that re- 
solves to a memory address. You can modify memory 
while you view it in either hex or ASCII. Hex values 
can be displayed in a variety of formats, including 
bytes, words, longs, and IEEE floats, and can be fol- 
lowed as pointers via local menu commands. 
Expressions can be evaluated at any time, and the 
format in which the result displays can be controlled. 
Expressions can modify variables directly by assign- 
ing values to them. In many cases, an expression can 
generate a value that is stored into memory. 


WATCHES AND INSPECTORS 


Turbo Debugger also understands variables at the 
source code level—and that’s where the real power 
of Turbo Debugger’s data access features becomes 
apparent. Turbo Debugger not only knows about lo- 
cal variables (automatic and static) and global vari- 
ables, but also knows about data types, pointers, ar- 
rays, structures, and unions. Named variables are 
automatically displayed according to their original 
source code data types in either the watches viewer 
window or the data inspector window. 

The watches viewer window, which normally occu- 
pies the bottom of the screen, is the standard way to 
keep an eye on the values of selected variables dur- 
ing program execution. This window lets you select 
one or more variables for display. (Actually, any ex- 
pression that resolves to a value may be displayed.) 
Structures and arrays can also be displayed. In addi- 
tion, any memory location displayed in the watches 
viewer window can be modified. 

Data inspector windows are something else alto- 
gether. These windows not only show the source 
form of variables, but can also readily follow point- 
ers, scroll through arrays, display nested structures, 
and the like. Where watches viewer windows are use- 
ful for posting the values of several variables, data 
inspector windows are ideal for delving into the de- 
tails of a specific variable or data structure. If the cur- 
sor is located on the name of an array, pressing 
Ctrl-I pops up a data inspector window for that array 
on the spot. If the cursor is located on the name of 
a pointer, an inspector can be popped up to show 
that pointer’s referent, and another data inspector 
window can even be popped up from the first inspec- 
tor to show additional information about the refer- 
ent. Data inspector windows can be chained to fol- 
low a linked list of pointers, or to examine an array 
of structures or a structure that contains arrays. 

The data addressed by any expression that re- 
solves to an address can be inspected, and type- 
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casting can be performed on any such expression. 
Variables that appear in the module and watches 
viewer windows can be inspected simply by pressing 
Ctrl-I. Variables in a data inspector window can be 
modified. Functions, local variables, and passed pa- 
rameters can even be inspected by selecting them 
directly from the source code in a module viewer 
window. 

More than any other feature, the data structures in 
modern programming languages set these languages 
apart from their predecessors. With data inspector 
windows, Turbo Debugger puts data structures at 
your fingertips. 


THE DEATH OF HEISENBERG 

Turbo Debugger offers a number of advanced fea- 
tures that let you take on debugging problems that 
go beyond the merely difficult to the brutal. One 
such problem is the debugging of very large pro- 
grams. The difficulty here is that a large program, a 
debugger, and the information that the debugger 
needs to maintain about the program often can’t all 
fit into the 640K DOS address space at the same 
time. Turbo Debugger provides three different solu- 
tions to this problem. 


EMS storage. First of all, Turbo Debugger can store 
the table of information about a program’s symbols 
in EMS memory (if EMS memory is present), thereby 
freeing the DOS memory that the table normally oc- 
cupies and making that DOS memory available to 
the program being debugged. Furthermore, EMS 
memory can be shared between Turbo Debugger 
and the application being tested. 


Separate but linked. Second, if two computers are 
available during development, Turbo Debugger can 
be moved away from the target application to run on 
another PC altogether, with debugging control taking 
place over a serial link between the two machines. In 
this configuration, Turbo Debugger needs only about 
10K RAM on the target computer. This leaves plenty 
of memory for the application. 


Virtual-86 partitions. Turbo Debugger’s third solu- 
tion to the problem of debugging large applications 
is particularly exciting. Turbo Debugger can take ad- 
vantage of the virtual-86 feature of the 80386 and 
split memory into a virtual-86 partition for your ap- 
plication being debugged and a 386 protected mode 
partition for Turbo Debugger. This arrangement car- 
ries two benefits: First, any program that runs on a 
PC system can be debugged, no matter how large the 
program is. Second, the program being debugged 
loads at exactly the same memory location in the vir- 
tual PC as the program would in a standard PC if 
that program weren’t being debugged, and the nor- 
mal amount of memory is available in the PC for the 
program to use. As a result, in 80386 mode Turbo 
Debugger eliminates the interference with the target 
program that other debuggers inevitably introduce. 
This interference is sometimes called the “Heisen- 
berg effect,” after the famous physicist who demon- 
strated that it’s impossible to observe subatomic 
interactions without altering them. With the combi- 


nation of Turbo Debugger and a 386, it’s possible to 
observe a program’s inner workings without the ob- 
server getting in the way. 


SCREENS AND KEYS 


Another problem that arises during the debugging 
process is that both the debugger and the target ap- 
plication want to use the entire screen display. Turbo 
Debugger offers a number of screen-handling solu- 
tions. The debugger can switch between the user 
screen and the debugger screen, use a second dis- 
play, use the extra text pages of color adapters, or 
turn off user display updating altogether. If none of 
these options is ideal for a particular program, the 
two-machine remote debugging approach described 
earlier, which solves all display-related problems, can 
be used. 

Turbo Debugger allows the text editor of your 
choice to be invoked directly from the debugging en- 
vironment. You can then return to the debugger and 
make changes to programs (or to data files) the in- 
stant you recognize a bug. Similarly, files can be 
viewed and modified directly from a file viewer 
window. 

Keystroke sequences can be assigned to keys, and 
those keys can then be used instead of lengthy hand- 
typed command sequences. These keyboard macros 
are useful for quickly returning to a specific place in 
a program; once the key sequence that gets you to a 
given point is recorded, you can return to that point 
at any time with a single keystroke. 

Turbo Debugger can disassemble all 8086, 80286, 
80386, 8087, 80287, and 80387 instructions, both real- 
and protected-mode. It can also assemble all 8086, 
80286, 8087, 80287, and 80387 instructions, plus most 
80386 instructions. Turbo Debugger provides full 
support and a special window for the 87-family nu- 
meric coprocessor. 

Turbo Debugger is, as you’d expect, designed to 
complement the latest generation of Turbo lan- 
guages: Turbo C 2.0, Turbo Pascal 5.0, and Turbo As- 
sembler 1.0. The current releases of Turbo Basic and 
Turbo Prolog are not supported, but future releases 
will be supported. If you use a compiler or assembler 
from another vendor, you may still be able to use 
Turbo Debugger, since it also supports programs 
compiled for use with Microsoft’s CodeView de- 
bugger through a conversion utility. In addition, you 
can always debug any program at the assembler level 
with Turbo Debugger, regardless of the language 
with which the program was created. 


WHEN DO YOU NEED TURBO DEBUGGER? 


Now that you have an idea of what Turbo Debugger 
can do, the next question is when you might need to 
move up from integrated debugging with your favor- 
ite Turbo language to Turbo Debugger. 


More and better. Turbo Debugger can help when you 
feel that you need more sophisticated breakpoints, 
or better display of data structures, than integrated 
debugging offers. For example, if a given flag is set 


to an incorrect value every 50 times that a function 
is called, you’d be much better off having Turbo De- 
bugger break on the incorrect value, rather than 
break on the function 50 times in the integrated de- 
bugger so that you have to manually check the value 
of the flag each time. 

Similarly, if you’re having problems with nested 
structures, structures of arrays, or complex pointers, 
Turbo Debugger is the way to go. The data inspector 
windows of Turbo Debugger are simply the best tool 
around for examining complex data structures. 


Low-level action. Turbo Debugger becomes abso- 
lutely necessary when you need to observe low-level 
machine functions in action. Integrated debugging 
is confined to entities that are defined by and under- 
stood by the high-level language that this debugging 
serves: constants, variables, and high-level language 
statements. If your program directly accesses DOS 
functions, BIOS functions, BIOS variables, interrupt 
vectors, display memory, or I/O ports; if you need to 
access memory directly from the debugger or need 
to know the actual addresses of variables; or if you’re 
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PURART’S TRAPPER 
BOARD 


Turbo Debugger’s 386 hardware debug support 
proved to be so compelling during testing that a 
hardware manufacturer has designed and is now 
offering a low-cost support board for non-386 sys- 
tems. Trapper provides a single hardware break- 
point that may be set to trigger on one contiguous 
range of memory or I/O addresses. The trigger 
may be set to occur either when any address 
within the range is accessed, or when any address 
outside of the range is accessed. Trapper can be set 
to recognize read accesses, write accesses, or both. 
Thus, Trapper could trap intended writes to a 
buffer that “miss” the buffer somehow, or it could 
trap unintended writes to a DTA or to the inter- 
rupt vector jump table. The board can also distin- 
guish between data and instruction access, thus al- 
lowing (among other things) for breakpoints to be 
set in ROM. 

Trapper does not contain protected RAM in the 
fashion of Periscope Corporation’s Submarine 
board, nor is it intended to compete with high- 
end hardware debug products such as those from 
Periscope and Atron. The idea is to give 8088 and 
286 programmers some of the same hardware as- 
sistance that 386 users can tap from the CPU itself. 

Trapper was designed by Purart, Inc., of Hamp- 
ton Falls, New Hampshire, and will sell for 
$149.95. For more information, contact: 


ImageSoft 

6-57 158™ Street 
Beechhurst, NY 11357 
(718) 746-9069 


—Michael Abrash 
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* Turbo C 2.0 program for use in a sample Turbo Debugger 
* debugging session. The bug: The Text array in the 
* TextBlock structure does not include space for the 
* terminating zero byte. The solution: Dimension the 
* Text array to (BUFFER_LENGTH + 1) characters in Length. 
* 
* 


By Michael Abrash 6/18/88 
“/ 


#include <stdio.h> 
#include <alloc.h> 


/* Number of characters buffered per text block. */ 
define BUFFER_LENGTH 20 


/* Structure we'll use to store text in. These structures 
are combined into a singly linked list, with one 
structure per allocated memory buffer. */ 

struct TextBlock { 
char Text [BUFFER_LENGTH) ; /* text buffer */ 
struct TextBlock *NextTextBlock; /* pointer to next 

text block */ 

5 


main() 


int c; /* temporary storage for a character */ 
int Done = 0; /* set to 1 when all text is buffered */ 
int TextCount; /* location in the current text buffer */ 
struct TextBlock *FirstTextBlock; 

/* Points to the text block that 

starts the linked chain. */ 

struct TextBlock *CurrentTextBlock; 

/* points to the current text block */ 
struct TextBlock *NewTextBlock; 

/* points to the next text block */ 


/* Get the initial text block */ 

if ( !(FirstTextBlock = CurrentTextBlock = 
malloc(sizeof(struct TextBlock))) ) € 
/* We couldn't get any memory */ 
printf("Out of memory\n"); 
exit(1); 

> 


/* Buffer the text the user types, allocating memory as 
it's needed */ 
TextCount = 0; 
while ( IDone ) € 
/* Get the next character */ 
c¢ = getchar(); 
if ( c == EOF ) € 
/* It's the end of the file, so we're done */ 
/* Put @ zero at the end of the current buffer, 
making it a string */ 
CurrentTextBlock->Text[TextCount] = 0; 
/* Mark that this is the last text block in the 
linked list */ 
CurrentTextBlock->NextTextBlock = 0; 
/* We've gotten all the text */ 
Done = 1; 
)d else 
/* Buffer the character */ 
CurrentTextBlock->Text [TextCount++] = toupper(c); 
if ( TextCount >= BUFFER_LENGTH ) ¢ 
/* This buffer's full, so allocate another 
text block */ 
if ( !(NewTextBlock = 
CurrentTextBlock->NextTextBlock = 
malloc(sizeof(struct TextBlock))) ) ¢ 
/* We couldn't get any more memory */ 
printf("Out of memory\n"); 
exit(1); 


d 

/* Put @ zero at the end of the current buffer, 
making it a string */ 

CurrentTextBlock->Text[TextCount] = 0; 

/* Start buffering at the beginning of this 
text block's text buffer */ 

TextCount = 0; 

/* Make the newly allocated text block the 
current text block */ 

CurrentTextBlock = NewTextBlock; 


/* Print out the uppercase result, starting with the 
text stored in the first text block and continuing 
until the last text block (the text block with a 
null link) has been displayed */ 

CurrentTextBlock = FirstTextBlock; 

do { 
printf("%s", CurrentTextBlock->Text); 
CurrentTextBlock = CurrentTextBlock->NextTextBlock; 

> while ( CurrentTextBlock ); 
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THE VIEW FROM WITHIN 
continued from page 57 


interested in the actual assembly language code gen- 
erated by Turbo Pascal or Turbo C, you need Turbo 
Debugger. 


A SAMPLE SESSION 


In this section, I'll show how Turbo Debugger lets 
you catch a subtle bug that could be infuriating to 
find when using a less-capable debugger. Listing 1 
shows a Turbo C program that stores any amount of 
typed text (converted to uppercase) in a linked list of 
structures, which are allocated on the fly as they’re 
needed. When all of the text is entered, the program 
prints the uppercase text. The task is simple enough, 
but a bug turns up when the program is run and the 
following lines are typed in: 

First line 

Second line 

Third line 

Fourth line 

Fifth Line 

Sixth line 

Z 

When these lines are entered, the text shown in Fig- 
ure 3 results. 

Clearly, something is wrong—but where? To get a 
handle on the problem, load the program into Turbo 
Debugger and move the cursor to the following line, 
located just before the final do loop: 


CurrentTextBlock = FirstTextBlock 


Pressing F4 at this point instructs Turbo Debugger to 
execute the program to this line and then to stop. Af- 
ter the six lines of text are entered, Turbo Debugger 
breaks at the selected line and brings up the debug- 
ging interface. At this point, all of the entered text is 
supposed to have been stored in a linked list of 
TextBlock structures. 

Here, data inspector windows can be used to great 
advantage. To create a data inspector window, press 
Ctrl-I with the cursor positioned over any occurrence 
of FirstTextBlock in the module viewer window. The 
window that appears shows the first TextBlock struc- 
ture, which contains the first 20 text characters and 
a pointer. This structure looks fine, so move the cur- 
sor to the NextTextBlock field of the structure and 
press Ctrl-I again to pop up another inspector that 
follows the link to the next block. The result is 
shown in Figure 4. 

Figure 4 makes it plain that something is wrong with 
the location to which the NextTextBlock field of 
FirstTextBlock points. The data inspector windows 
show clearly that the block of data to which the first 
link points does not contain the correct text. Two ex- 
planations are possible: at some point in the pro- 
gram, either the second TextBlock structure is filled 
with garbage, or else the NextTextBlock field of 
FirstTextBlock is set to point somewhere other than 
to the second TextBlock structure. 

Turbo Debugger lets you check both cases simul- 
taneously. First, set the program back to the start by 
selecting Program Reset from the Run menu. Then 
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Figure 3. The bug’s telltale. Bugs 
have an affinity for “garbage” in pro- 
grams, much as they do in real life. 
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text stored in the first text block and continuing 
until the last text block (the text block with a 
null link) has been displayed */ 
> CurrentTextBlock = FirstTextBlock; 
do { 
printf(’%s", Cur @5584:FFCE : ds:@69C 


CurrentTextBlock Text 


} while ( CurrentTe Next Text® lock ds :8880 


} 


Next TextBlock 


struct TextBlock * 


"FIRST LINENWSECOND LI" ack; 


Figure 4. Using inspectors to trace 
pointer referents. 


move the cursor to the second occurrence of 
CurrentTextBlock->Text[TextCount] = 0 and press 
F4; this step runs the program up to the point at 
which FirstTextBlock->NextTextBlock is set. After 
the following text is typed in, the breakpoint is 
reached, and the debugger interface comes up: 


First line 
Second line 

Now, put a watch on FirstTextBlock->Next- 
TextBlock by selecting Watch... from the Data menu 
and entering the following: 


FirstTextBlock->NextTextBlock 
The watch shows that the next text block is at offset 
8C6H. Use the Changed memory global... selection 


in the Breakpoints menu to instruct Turbo Debugger 
to stop whenever the value of the FirstText- 


Block->NextTextBlock field is changed. Now, if any 
line in the program modifies the pointer to the sec- 
ond text block at any time, Turbo Debugger breaks 
back to the user interface, so there’s no way that the 
link to the second block can possibly be trashed 
without you knowing about it. 

The other possible cause of the problem is trash- 
ing of the text in the second text block. To check this 
possibility, put a breakpoint at the line that stores 
each character: 

CurrentTextBlock->Text [TextCount++] = toupper(c) 


To do so, move the cursor to that line, and press F2. 
This step allows you to ensure that the correct char- 
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jodule: demo File: demo.c 86 


Inspecting FirstTextBlock->Texte 


THE VIEW FROM WITHIN 
continued from page 59 


acters are being stored to their proper location. 
Once you’ve verified that the block is filled properly 
(if it is), you can set a breakpoint on any modifica- 
tion of the first character of the Text field of the sec- 
ond TextBlock structure in order to catch any state- 
ment that might be trashing that block. 

We’re ready to catch the bug. Run the program by 
pressing F9, then sit back and watch the results 
come in. 

In this case, you won't have to wait long. The pro- 
gram breaks on the very next line: 


TextCount = 0 


This means that the following line changed 
FirstTextBlock->NextTextBlock: 


CurrentTextBlock->Text [TextCount] = 0 


The watches viewer window agrees, reporting that 
FirstTextBlock->NextTextBlock has changed to 
800H. 

How could this possibly have happened? Veteran 
programmers will spot the problem right away: Text- 
Count points past the end of the Text array, so that 
the final zero is stored right over the variable that re- 
sides immediately after Text; this variable just hap- 
pens to be NextTextBlock. Since the lower byte of 
NextTextBlock is forced to zero, NextTextBlock 
now points not to the next text block, but rather to 
some random area of memory. Thus, the link be- 
tween the text blocks is broken. The fix is a simple 
matter of dimensioning the Text array to BUF- 
FER_LENGTH-+1 characters in size. 

Let’s examine how to narrow the cause of the bug 
further (as we would have needed to do in this ex- 
ample if we hadn’t immediately recognized the na- 
ture of the problem). Bring up a watch on Text- 
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Figure 5. The problem’s solution. 
TextCount points past the end of the 
Text array. A zero has been written 
over the first byte of the next variable 
in memory, which is part of pointer 
NextTextBlock. The corrupted pointer 
points to a random location, where 
garbage lives. 


Count (which reveals that TextCount is 20 at this 
point in the program), and then bring up an inspec- 
tor on FirstTextBlock->Text and scroll to the end of 
the Text array (at this point, the data inspector win- 
dow appears as shown in Figure 5). The inspector 
shows that Text is only 20 characters long, and won’t 
let you scroll past element 19; at the same time, the 
watches viewer window shows that TextCount is 20. 
To go further still, we could create two dump viewer 
windows to dump the memory at both 
FirstTextBlock->Text[TextCount] and 
FirstTextBlock->NextTextBlock; these windows 
would show that both variables refer to the same 
address. That should narrow it down enough for 
anyone! 


WINDOWS WITH A VIEW 


The ability to see what happens within a program is 
by far the largest part of finding any bug. Turbo De- 
bugger offers the power to watch every part of a pro- 
gram in action, from the high-level statements of the 
host language through the binary representations of 
large data structures, down to the bare machine reg- 
isters and memory locations. In a program, many 
things happen at once—Turbo Debugger’s win- 
dowed architecture lets you keep an eye on them all. 
It makes good use of any machine’s resources, but 
it’s especially powerful when paired with the 80386 
CPU. 

Turbo Debugger makes large-scale development 
with the Turbo languages easier and faster than ever 
before. The view is the power—look into it. 


Michael Abrash is a senior software engineer at Orion 
Instruments, in Redwood City, California. 


Listings may be downloaded from Library 1 of Compu- 
Serve forum BPROGB, as DBDEMO.ARC. 
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TURBO C 


TURBO C 2.0: THE THRILL 
OF THE HUNT 


Turbo C 2.0 goes one better with integrated debugging! 


Kent Porter 


SQUARE ONE 


Turbo C has always offered a great “bang 
for the buck.” The initial release of Turbo 
C provided over 350 library functions, an 
integrated development environment, 
and a variety of utilities to aid in program 
development. Turbo C 1.5 (introduced last 


LISTING 1: FACTORL.C 


/* FACTORL.C: Computes factorial of a keyed number */ 
/* Repeats until user enters 0 */ 


#include <stdio.h> 


main () 
{ 


winter) took a giant step forward with the addition of 
the BGI graphics library. Now, Turbo C 2.0 is here— 
and with the improvements to the toolset, including 
integrated debugging, the language takes another do-£ 
quantum leap. i pag 

Since Turbo C’s debugging features have garnered value = atoi (input); 
so much interest, this article deals primarily with the YR eernetorlal «wane, rec aoueas 
Integrated Debugger. First, however, let’s take a else ; . en 
quick tour of all of the enhancements in Turbo C 2.0. Caan ee ee 


> while (value); 
MEET THE NEW TURBO C 


For convenience, I’ve grouped Turbo C’s new and 
expanded features into three categories. 


int value, atoi(); 
long fact(); 
char input [6]; 


long fact (int val) 
{ 
long result = 0; 

if (val) 


result = val * fact (val-1); 
return (result); 


Language Enhancements. 

® Floating point emulation is faster. 2 

© Long doubles are now supported for greater nu- 
meric precision. 

@ The obsolete ssignal and gsignal functions (which 
are leftovers from Unix System III) have been 
dropped in favor of signal and raise. This change 
improves compatibility with Unix System V. 

Expanded Utilities. 

@ Turbo C 2.0 contains a new .OBJ file cross- 
reference utility. 


e TLINK now generates .COM files from programs 
that are compiled in the Tiny model. 


@ MAKE supports autodependencies. 

New Tools of the Trade. 

® Compiles and links are 10-20 percent faster. 
© The Turbo C editor can use EMS for the edit 


buffer. This can save up to 64K of memory for 
compiling and running the program. 
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® Wildcards can be expanded on 
the application program’s com- 
mand line. 


©@ The integrated environment 
takes advantage of dual mon- 
itors. 

@ The editor supports unindent, 
block indent/unindent, and 
optimal fill. 

@ And, of course, Turbo C 2.0 
offers interactive debugging. 


The most apparent changes are 
in the integrated environment. 
The menu bar across the top of 
the screen is a little more crowded 
by the addition of a Break/watch 
selection. Every selection (except 
Edit) now has an associated pull- 
down menu for greater control 
over various aspects of the envi- 
ronment and the programming/ 
debugging session (more on this 
presently). 

Overall, the environment— 
while more comprehensive and 
flexible—retains the same general 
look and feel of Turbo C’s pre- 
vious generations. Unlike the tran- 
sition from Turbo Pascal 3.0 to 4.0, 
there’s no “culture shock” in mov- 
ing to Turbo C 2.0. But there is 
plenty to learn, so let’s take a look. 


INTEGRATED DEBUGGING 


It’s tempting to say that Turbo C 
2.0 has added a debugger, but the 
fairer statement is that debugging 
has been integrated into the 
Turbo C environment. Unlike 
most debugging packages, Turbo 


C’s Debugger is not a standalone 
utility. Rather, it’s an integral part 
of the environment, seamlessly 
folded into the process of writing, 
making, and testing programs. 

During a debugging session, for 
example, you can edit and remake 
the source code to fix errors, then 
resume the debugging process. 
The recompile doesn’t lose track 
of breakpoints and watches that 
were set earlier; they remain in ef- 
fect even if source code is added 
or removed. This allows you to 
work out the bugs systematically, 
without disrupting the natural 
workflow. 

The power of the C language 
has its price: no matter how 
skilled the programmer, it’s almost 
impossible to write a C program 
that runs right the first time. The 
language’s flexibility and some- 
times obscure syntax encourage 
new techniques, and this experi- 
mentation inevitably introduces 
bugs. Therefore, Turbo C and in- 
tegrated debugging go hand-in- 
glove. 


THE HUNT 


To see how a debugging session 
proceeds, let’s develop and debug 
a simple program to compute the 
factorial of a number. To refresh 
your memory (in case your alge- 
bra has gotten rusty), a factorial is 
the series product of a value. For 
example, the factorial of 5 (written 
5! in mathematical notation) is 
computed as 1 X2X3X4X5, 
which equals 120. 


FACTORL.C (Listing 1) has a 
loop in main that repeatedly asks 
for a value and prints the value’s 
factorial until the user types 0. 
FACTORL uses the recursive 
function fact to solve for the fac- 
torial. The program as listed con- 
tains a bug; we'll hunt the bug 
down in order to examine a few 
of the Debugger’s features. 

The process of editing and 
making a program in the develop- 
ment environment has not 
changed from Turbo C 1.5. The 
process of running the program, 
however, is a little different. The 
Alt-R command now produces a 
menu that includes some debug- 
ger controls. You can circumvent 
the menu and run the program by 
using the new hotkey, Ctrl-F9. 

When the program is run, it re- 
turns 0 as the factorial of any 
number. Thus, the fact function 
appears to contain a bug. 

To prepare a program for de- 
bugging, an environmental con- 
dition must be set: toggle Source 
debugging (located on Turbo C 
2.0’s revised Debug menu) to On 
(see Figure 1). Also, since you’re 
dealing with a recursive function, 
you might want to check the call 
stack to make sure that the recur- 
sion is working properly. To do so, 
set Standard stack frame On from 
the Options/Compiler/Code gen- 
eration menu. Now, remake the 
program and you're ready to go. 
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Col 1 


Line 1 Insert Indent Tab 


Figure 1. Examining the call stack. 


Col 11 Insert Ind 


Call Stack 


return (result); 


THE HUNT 
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THE PROBLEM 


The program runs normally until 
the fact function is called from 
within printf. At that point, stop 
the program and observe what’s 
going on. Set an automatic stop 
(called a breakpoint) by moving the 
cursor to the statement if(value) 
and pressing Ctrl-F8. (As an alter- 
native approach, select Toggle 
breakpoint from the Break/watch 
menu.) Notice that the source line 
is highlighted to indicate that it’s 
a breakpoint. Now, run the pro- 


gram. 


The new “smart screen” option, 
which is on by default, automat- 
ically swaps between the edit 
screen and the program display. 
Whenever screen I/O occurs, the 
program display appears. Conse- 
quently, the program runs nor- 
mally and asks for and receives 
values until it hits the breakpoint. 
The edit screen then reappears. 

A bar, called the execution bar, 
highlights the source line where 
the program stopped. 

One way to proceed is to single- 
step, executing one line at a time, 
and watch what happens. The 
Turbo C 2.0 Debugger has two 
single-step hot keys. F7 activates 
Trace, which single-steps through 
all function calls. F8 activates Step, 
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Figure 2. The evaluation window. 


which “steps over” functions, exe- 
cuting them but not tracing their 
execution. In this case, since the 
bug is probably in the function, 
select F7. 

However, there’s an easier way 
to locate the source of the prob- 
lem. Whatever the value you 
keyed, fact calls itself that number 
of times before it encounters the 
return statement. You can save a 
lot of single-stepping by setting a 
temporary breakpoint at the re- 
turn. To do so, position the cursor 
on the return statement, then se- 
lect Go to cursor from the Run 
menu. The program halts when it 
reaches the line where the cursor 
is positioned. 

Now you can examine the state 


of affairs. First, check the call 
stack to see if recursion is working 
correctly (select Call stack on the 
Debug menu). Assuming that the 
keyed value is 3, this produces the 
display shown in Figure 1. Note 
that each invocation of fact is 
passed an argument that is one 
less than its predecessor. This is 
as it should be. So where’s the 
bug? 

The program consistently re- 
ports 0 as the factorial. Examine 
the argument of return to see 
what the fact function is return- 
ing. To do so, place the cursor on 
result, then press Ctrl-F4 (or select 
Evaluate from the Debug menu). 

Ctrl-F4 pops up the expression 
evaluation window shown in Fig- 
ure 2. A number of things can be 
done in this window, such as typ- 
ing expressions using C syntax 
and viewing the results, or chang- 
ing the value of a variable. In this 
case, you simply want to see re- 
sult’s value. The Debugger copies 
the variable name from the cursor 
position into the evaluate field. 
Press Enter and the value appears 
in the middle box. The value that 
displays is zero, which explains 
why the program returns incorrect 
results. 


THINKING IT THROUGH 


A debugger is a tool for interac- 
tively controlling and watching 
the execution of a program, and 
for examining the program’s in- 
ternal conditions. The debugger 
can tell you what’s happening, but 
it can’t think for you. The ques- 
tion is, “Why is the value returned 
in result equal to 0?” To find the 
answer, you have to inspect the al- 
gorithm that yields this value. 

In the fact function, result is 
initialized to 0. Then, if the argu- 
ment has a nonzero value, result 
is assigned the value of the ex- 
pression, which triggers a recur- 
sive call. When the passed argu- 
ment reaches 0, the if statement 
fails and the return statement 
sends back the original value of 
result (0). This value becomes one 
of the multipliers in the factorial 
series: 


OR 1 2% SX ae OGN 


Zero times anything else is zero. 
Consequently, the bug is the result 
of flawed logic; result should be 
initialized to 1 so that the function 
cannot return 0. 


To fix the program, change the 
initializer, remake FACTORL, and 
test the program again. This time 
the program returns the correct 
answer, and the bug is fixed. 


STICKY BREAKPOINTS 


An interesting thing happens 
when you remake a program that 
contains set breakpoints; the 
breakpoints are retained, even if 
source lines are added or re- 
moved. The Turbo C 2.0 Debugger 
tracks the physical source lines 
that have breakpoints. When a 
program is complex and buggy, 
this automatic tracking process 
saves you the hassle of reestab- 
lishing breakpoints every time you 
fix and retry. These “sticky break- 
points” are one of the great ad- 
vantages of having the Debugger 
integrated into the editing envi- 
ronment, rather than designed as 
a separate utility. 


WATCHING VARIABLES 


Another feature of the Turbo C 
2.0 Debugger is the ability to 
watch one or more variables in a 
window while the program exe- 
cutes. This is particularly valuable 
when a loop counter goes berserk, 
or when some variable appears to 
have been corrupted for reasons 
unknown. The easiest way to set 
watches on variables is to position 
the cursor on some occurrence of 
the variable to be watched. For 
each variable, press Ctrl-F7 (or use 
the Add watch selection in the 
Break/watch menu). The watch 
window appears at the bottom of 
the display, similar to the error/ 
warning message window that ap- 
pears during compiles. Also, F5 
can be used to toggle between full 
(zoomed) and split-screen mode, 
and F6 switches between full- 
screen edit and watch windows. In 
split-screen mode, the watch win- 
dow grows upward dynamically to 
accommodate the number of 
watched variables. 

Local variables are visible only 
while control resides within the 
routine that owns them. There- 
fore, as execution proceeds from 
one routine to another, the auto 
variables located outside of the 
current routine become unde- 
fined. The watch window only 
shows values for the variables that 
it sees. (This explains the “Unde- 
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ile dit try ompile 


printf (’\nValue? "); 
gets (input); 
value = atoi (input); 


ro ject 
Edit 


ptions ebug reak/watch 


printf ("\nFactorial = %ld\n", fact (value)); 


else 


puts ("\nCamot take factorial of negative number\n"); 


} uhile (value); 


} 


long fact (int val) 
{ 
long result = @; 


result = val * fact (val-1) 
return (result); 


} 


Watch 


-He lp 


—Zoom -Switch -Trace 
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fined symbol” message associated 
with value in Figure 3. The execu- 
tion bar shows that control is cur- 
rently in fact; value, however, is 
local to main.) Global variables 
are, of course, visible from any- 
where in the program. 

The Break/watch menu pro- 
vides options for changing and 
deleting watches, as well as for 
removing all watches at the same 
time. Similar capabilities are avail- 
able for controlling breakpoints. 

If you want to watch certain ele- 
ments within an array, you can 
use a watch editor feature called 
repeat counts. For example, to 
watch elements 4 through 8 of an 
array called num, specify the ele- 
ments as the following: 


num[4] ,5 


This statement tells the Debugger 
to watch the five elements of num, 
starting at subscript 4. The watch 
window then contains individual 
entries for each element, building 
upward from num[4]. 

If you’re working with a large 
application that involves many 
source modules, you can qualify 
variable names from other mod- 
ules in order to watch their values. 
This is true even if the variable 
comes from a module outside of 
the module you're currently de- 
bugging, and the variable is local 
to a specific function. The general 
form of the syntax for the watch 
editor is: 


-Step -Make Menu 


-module. function.variable 


The module must be made with 

the debugging options on. How- 
ever, the module doesn’t have to 
be in the editing environment in 
order to watch its indicated vari- 
able while the program runs. 


SMART SCREEN SWITCHING 


With many debuggers, the process 
of debugging graphics applica- 
tions is often tricky (and some- 
times impossible)—but not with 
the Debugger in Turbo C 2.0. The 
Turbo C 2.0 Debugger operates in 
text mode, while the program dis- 
play is in graphics mode. The 
smart screen management built 
into the Debugger lets you switch 
back and forth readily. The pro- 
gram display can be viewed at any 
time, regardless of its mode, by 
pressing Alt-F5. Pressing any key 
returns you to the edit/debug 
screen. 


BAILING OUT 


You may be wondering what 
happens if your program hangs the 
system. If your program is running 
under the debugging environment, 
you can usually (but not always) es- 
cape by pressing Ctrl-Break, which 
returns you to the edit/debug 
mode. The Program reset option 
from the Run menu (or Ctrl-F2) re- 
initializes the program as if it had 
never been run before. With this 
option, you can start over and uti- 
lize breakpoints, watches, and other 
Debugger tools to pinpoint the 
problem. 


Figure 3. The watch window. 


Once you've perfected your pro- 
gram by using the Integrated De- 
bugger, simply turn off the envi- 
ronment’s debugging option and 
recompile. The debugging options 
insert some additional informa- 
tion into the end of the .EXE file; 
the final application will run with 
this debug information stil in 
place, but the .EXE file size will be 
smaller without it. This is in con- 
trast to some debuggers that place 
int calls in your code, forcing you 
to remove the debug information 
before running the final appli- 
cation. 


THE VELVET GLOVE 


The essence of Turbo C 2.0 lies in 
its enhancements to the toolset— 
primarily in its addition of a pow- 
erful Integrated Debugger that lets 
you test, fix, remake, and retest 
until your program works like it’s 
supposed to. Almost by definition, 
C is a language that encourages 
both extraordinary power and its 
accompanying bugs. Turbo C 2.0 
fits integrated debugging over the 
hand of C like a velvet glove—and 
hurdles the last obstacle to true 
programmer productivity. @ 


Kent Porter is a frequent contributor 
to TURBO TECHNIX. His next 
book, Stretching Turbo C, is due to 
be released this fail. 


Listings may be downloaded from 
Library 1 of CompuServe forum 
BPROGB, as FACTRL.ARC. 
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FLOATING POINT: 
THE SECOND WAVE 


When a number isn’t exactly a number, 
y 


Turbo C 2.0 can handle it. 


Roger Schlafly 


Turbo C is very good at handling 
numbers that represent quantities in the 
real world, as I explained in “Floating 
Point in Turbo C,” TURBO TECHNIX, 
January/February, 1988. Turbo C 2.0 now 
=—— enhances floating point support with bet- 
ter precision, better exception handling, and a 
means of dealing with numbers that aren’t exactly 
numbers. 

Turbo C 2.0 fully supports the IEEE standard for 
computer arithmetic (IEEE standards 754 and 854) 
when used with an 8087 math coprocessor. (If an 
8087 is not present and emulation must be used in- 
stead, certain exceptions exist that are primarily re- 
lated to denormals, as explained in my earlier article 
on floating point.) 


WIZARD 


GREATER PRECISION 

There is a very long road in California called El 
Camino Real. Near Silicon Valley, FORTRAN pro- 
grammers call it El Camino DOUBLE PRECISION. 
Lisp programmers, who claim it originally extended 
all the way to Mexico City, call it El Camino Bignum. 
Turbo Pascal programmers call it El Camino Extend- 
ed. Turbo C programmers can now call it El Camino 
long double, in honor of Turbo C’s new data type, 
which is called the “long double.” This type was 
created by the ANSI C committee (X3J11) to accom- 
modate the IEEE extended precision. Quite simply, 
long doubles are very long reals. 

Turbo C 1.0 and 1.5 actually allowed the long 
double syntax, but long doubles were identical to 
doubles. In Turbo C 2.0, the long double is a 10-byte 
data type, whereas floats and doubles are 4 and 8 
bytes in size, respectively (as in earlier releases of 
Turbo C). Turbo C automatically performs conver- 
sions among these types. 

Long doubles are just as fast as floats and doubles. 
The only penalty is the additional data space re- 
quired by long doubles. The following examples 
show the usefulness of long doubles. 


Increased precision. Suppose you want to take the 
sum of some number of real values in a vector. Such 
calculations are prone to roundoff error, which is 
why numerical analysts use tricks to carefully reorder 
the numbers in order to minimize the loss in preci- 
sion. A simpler alternative is to use long double pre- 
cision to compute the sum, as shown in the following 
example: 


double vect_sum(int n, double x[]) 


Int: is 
long double sum = 0; 
for Ci = 0; 7 < nz ++1) 
sum += x[i]; 
return sum; 
> 


Avoiding overflow and underflow. Turbo C has a hy- 
pot() library function, which returns the hypotenuse 
of the right triangle given the two remaining sides. 
This function is quite useful in calculating the modu- 
lus of complex numbers, in polar coordinate conver- 
sions, and in many other situations. If you were to 
create such a function, you would probably write it as 
follows: 


#include <math.h> 
double hypot (double x, double y) 
{ 


return sqrt (x*x + y*y); 

> 

The trouble with defining hypot() in this way is 
that it’s susceptible to underflow or overflow of inter- 
mediate results. For example, if x = 3e200 and 
y = 4e200, then hypot() overflows even though the 
correct answer is 5e200, which is nowhere near the 
overflow threshold of 1.8e308. Worse yet, hypot(3e- 
200,4e-200) underflows and returns 0, when it should 
return 5e-200. (This is worse because underflows are 
ignored by Turbo C Runtime code, and you'll have 
no idea that the function underwent a complete loss 
of precision unless you explicitly check for under- 
flows.) 

Now, examine the following hypot() function: 
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FLOATING POINT 
continued from page 67 


double hypot (double x, double y) 
€ 


long double z = x*x + y*y; 
asm FLD tbyte ptr z 
asm FSQRT 
De 


This hypot() function is similar to 
the hypot() function included with 
Turbo C, except that the Turbo C 
library function calls matherr() if 
an overflow or underflow occurs 
in the result (i.e., if the resulting 
long double is outside the limits 
allowed for doubles). Thus, the 
hypot() function shown above 
avoids the difficulties that occur 
with overflows and underflows. 

Some inline assembler was used 
here because the Turbo C sqrt() 
function requires a double argu- 
ment, rather than a long double 
argument. The 8087 operation 
FSQRT, however, returns a result 
of any desired floating point type. 
The process of returning a long 
double is the same as that of re- 
turning a double or a float, and 
the 8087 supports all three types. 
The results are returned on top of 
the 8087 stack, and the 8087 chip 
automatically performs the re- 
quired conversion when a num- 
ber is unloaded from the 8087 
stack. 


READING AND PRINTING 
LONG DOUBLES 

Long doubles can be read with 
scanf() or printed with printf() by 
using the L modifier for the usual 
floating point conversion specifi- 
ers. For example, the following 
code reads 7 from a string and 
prints it to 18 decimals: 

#include <math.h> 

#include <stdio.h> 

#define STRINGIZE(p) #p 

long double pi; 
sscanf(STRINGIZE(M_PI),"4Lf",&pi); 
printf("pi = %21.18Lf\n",pi); 


PASSING PARAMETERS 


The choice of using three floating 
point data types complicates pa- 
rameter passing conventions, and 
makes it all the more likely that a 
function will be called with the 
wrong type parameter. I recom- 
mend using ANSI C prototypes. 
Be extra careful with functions 


that cannot be adequately proto- 
typed, such as printf(). 

When passing a floating point 
expression without a prototvpe, 
Turbo C passes either a double or 
a long double, depending upon 
the longest type in the expression. 
ANSI C stipulates that the L suffix 
can be added in order to tell the 
compiler to consider a constant to 
be a long double. This step is 
demonstrated in the following 
example: 


printf("double constant = %g\n", 


printf("'Long double constant = 
%Lg\n",3.2L); 

Some ANSI C compilers may also 

require the L suffix in order to 

achieve full accuracy in situations 

such as the following: 

long double x, y; 

y= Sick > xX: 

With Turbo C, however, an L is su- 

perfluous in this situation. Turbo 

C automatically stores such con- 

stants to long double precision. 


PRECISION LOSS 
Let’s consider a simple example 
of an appropriate use of high pre- 
cision. Suppose you want to com- 
pute 1/3 to the power of n for var- 
ious positive integers n, and the 
answer must be accurate to about 
three decimal digits. Several av- 
enues of approach are possible: 
® Method 1. Call the Turbo C 
library function pow(3,-n). 
® Method 2. Recursively calculate 
x[n] = 3”: 
x(0] = 1 


x[n] = x{n-1] / 3 


® Method 3. Recursively calculate 
x[n] = 3”: 
x0] = 1 


for n>0O 


x{1] = 1./3 

x[n] = 

(31 * xin-1] - 10 * x{n-21) / 3 

for n> 1 

Method 1 is both the most ac- 
curate and the preferred method. 
It should yield a result that is ac- 
curate to full double precision. 

Method 2 is the most straight- 
forward approach if no library 
function is available. While meth- 
od 2 is quite accurate for small 
values of n, each operation causes 
a roundoff error. Still, roundoff 
errors tend to average out, and 
two or three significant digits are 
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lost only when n gets to be about 
600 (which is near the range limits 
for double precision anyway). 
Computing the powers with long 
double precision is a reasonable 
approach, and provides the reas- 
surance that the answer is as ac- 
curate as double precision allows. 

Method 3 is a rather silly way to 
compute powers, but it’s mathe- 
matically correct and similar to 
the methods that are frequently 
encountered in practice. Unfortu- 
nately, this method is almost com- 
pletely useless. In single precision, 
it delivers an answer that is accu- 
rate to three digits only if n <= 4. 
Larger values cause the method to 
yield garbage. Method 3 returns 
answers for some higher values of 
n by using high precision, but the 
gain is minimal. Double precision 
only works for n <= 10, and long 
double precision only delivers 
three-digit accuracy when 
n<= 12. 

The lesson here is that most 
good numerical algorithms are 
stable with respect to roundoff er- 
ror, and that they deliver much 
more precision than could ever be 
used anyway. Poor numerical al- 
gorithms can lose so much preci- 
sion that they’re often useless, 
even when plenty of precision is 
available in the variables. 


DEALING WITH THE 
INFINITE 


The enemies of numerical ana- 
lysts are roundoff error, overflow, 
underflow, and division by zero. 
All of these situations involve nu- 
meric values that cannot be fully 
expressed in a finite number of 
bits. These anomalous values can 
infiltrate your program and create 
havoc. The usual countermeasure 
used by Turbo C and other C com- 
pilers is a form of Mutual Assured 
Destruction (MAD). If you give 
Turbo C a floating point expres- 
sion that blows up, it retaliates by 
nuking your program, which 
abruptly terminates with a mes- 
sage such as: 

Floating point error: Overflow. 
The alternative is to negotiate 
your own INF treaty. The idea is 
to come to terms with the infinite, 
and learn to live with it. 


The numbers won’t get out of 
control as long as the 8087 control 
word is set properly. The control 
word can be set to mask numeric 
exceptions via a call to _control- 
87() as follows: 

#include <float.h> 
_control87(MCW_EM-EM_DENORMAL, 
MCW_EM); 
The second argument is the mask 
that tells _control87() which bits 
are being changed in the 8087 
control word. The first argument 
specifies the new bit values that 
correspond to the exceptions that 
are to be masked. The invocation 
shown above masks all of the ex- 
ceptions except the denormal ex- 
ception. Denormal exceptions are 
largely harmless, because the 
Turbo C 2.0 Runtime Library con- 
tains a denormal exception han- 
dler. 

The creation of denormals can 
be regarded as mildly criminal be- 
havior on the part of the 8087 
chip. In dealing with denormals, 
the 8087 tries to get something for 
nothing. A denormal is a number 
so small that it should be zero, but 
the 8087 gives the number a pro- 
bationary nonzero status. This 
petty offense probably won’t 
bother your program. However, 
an annoying feature of the 8087 
chip is that it doesn’t have much 
of a rehabilitation program for de- 
normals. If a denormal value in- 
creases beyond a certain point, 
the denormal can reenter the 
range of the normals—in doing 
so, however, the value does not 
become normal. Instead, it be- 
comes unnormal. Unnormals are 
like convicted felons who have 
not been rehabilitated. They are 
not normal, they corrupt whatever 
values they touch, and they can- 
not even be stored in float or 
double format. You don’t want 
these animals in your neighbor- 
hood. 

Fortunately, Turbo C 2.0 goes 
the 8087 one better with a denor- 
mal exception handler that nor- 
malizes denormals before they 
mutate into unnormals. Turbo C 
normalizes denormals automati- 
cally when the denormal excep- 
tion is left unmasked. Note that if 
an 80386 machine has an 80387, 


it doesn’t matter whether the de- 
normal exception is masked or 
not. The 80387 has a built-in nor- 
malizer, and doesn’t generate un- 
normals at all. 


THREE NEW “NUMBERS” 


All of the other exceptions may be 
safely masked (and, in fact, that 
approach may be preferred for 
bulletproof programs). With de- 
normals properly normalized, the 
IEEE standard allows every arith- 
metic operation to have a defined 
result. The standard accomplishes 


this end by adding the following 
three new numbers: 


+INF plus infinity 
- INF minus infinity 
NAN not-a-number 


Two infinities. Having two infin- 
ities is new to Turbo C 2.0. Early 
drafts of the IEEE standard called 
for two infinity modes—“projec- 
tive” and “affine.” While the 8087 
supports both, it defaults to pro- 
jective infinity; Turbo C 1.0 and 
1.5 only supported projective in- 
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FLOATING POINT 
continued from page 69 


finity. However, projective infinity 
was dropped from the standard 
and is now obsolete. In keeping 
with the new IEEE standard, the 
80387 supports only affine infinity, 
as does the Turbo C 2.0 8087 em- 
ulator. Only affine infinity will be 
discussed in this article. If you are 
still using Turbo C 1.0 or 1.5 with 
an 8087 or 80287, you can select 
affine infinity by calling _control- 
87(), as shown in the following 
code: 

#include <float.h> 
_control87(1C_AFFINE,MCW_IC); 
Hello, NAN. NAN is even strang- 
er, and its name is something of 
an oxymoron. NAN isn’t really a 
number (as its name implies), but 
it has a legitimate representation 
in each of the floating point for- 
mats. Actually, there are many 
such representable NANs, but the 
8087 generates only one, and that 
NAN will suffice for this discus- 
sion. 

Any arithmetic operation on 
floating point numbers results in 
either a traditional floating point 
number or else one of these three 
special numbers. Overflows be- 
come infinities just as underflows 
become zero, as shown in the fol- 
lowing example: 


double x = 1e-200 * 1e-200; 
returns x = 0 

double x = 1e+200 * 1e+200; 
returns xX = +INF 

double x = - 1e+200 * 1e+200; 


returns x = -INF 


If an operation is mathemati- 
cally undefined (such as 0/0), the 
result is NAN. One of the less ob- 
vious cases is that 1/0 = +INF. 
Mathematicians will tell you that 
1/0 is just as likely to yield -INF as 
+INF. Having 1/0 yield +INF is 
rationalized because 0 really con- 
sists of two numbers: +0 and -0. 
While the difference between the 
two numbers isn’t obvious because 
both zeros are numerically equal, 
there is a subtle difference be- 
tween +0 and -0 that is shown in 
the following relationship: 


(+0 == -0) 


Essentially, you have to divide by 
0 in order to see which zero is 
present. The rule is 1/+0 = 
+INF, and 1/-0 = -INF. 

The 8087 and 80287 (but not 
the 80387) support pseudozeros, 
which can occur when unnormals 
multiply and the product gets too 
close to (true) zero. Pseudozeros 
are also equal to zero, but they re- 
tain the taint of the unnormals 
that produced them. With the 
Turbo C 2.0 denormal handler 
preventing unnormals from occur- 
ring, pseudozeros shouldn’t ap- 
pear either. 

Arithmetic can also be per- 
formed on these special numbers, 
as the following example demon- 
strates: 


+INF + 5 = +INF 


1/+INF = +0 
+INF/+INF = NAN 
5 * NAN = NAN 


The constants +INF, -INF, and 
NAN as used in this example are 
not predefined in Turbo C. How- 
ever, you can easily create con- 
stants that have these special 
numbers as their values by re- 
membering that Turbo C (like 
most C compilers) evaluates con- 
stant expressions at compile time. 
Thus, INF and NAN can be 
created as constants with the fol- 
lowing definitions: 
#define INF (1./0.) 
#define NAN (0./0.) 
What are all these crazy numbers 
good for? When performing com- 
putations on a computer, it’s very 
important to have a closed arith- 
metic system. A closed arithmetic sys- 
tem means that every arithmetic 
operation yields a quantity that is 
somehow representable within the 
system. If a long sequence of op- 
erations is performed and the re- 
sult is a NAN, then a mathemat- 
ically invalid operation was 
performed somewhere along the 
way. Since the result of every ex- 
pression—including an invalid re- 
sult—is represented, the Runtime 
Library never has to throw up its 
hands in despair and crash. 
Another use for NANs is in 
creating “uninitialized” data. In C, 
all uninitialized data are initial- 
ized with 0 at startup. (That’s +0, 
not -0.) Occasionally, a variable 
must truly be recognizable as un- 
initialized through some unique 
nonzero value. A constant that is 
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defined as a NAN (as shown ear- 
lier) can be used to initialize the 
variable with the value NAN. 
Since any operation on a NAN 
yields a NAN, a faulty answer 
won't occur when calculations are 
accidentally performed with un- 
initialized data. 


READING AND PRINTING 
INF, NAN 


INF and NAN values may be read 
into variables and displayed, just 
as with any legitimate floating 
point value. If a value happens to 
be plus infinity, minus infinity, or 
not-a-number, then it’s printed as 
“INF,” “-INF,” or “+NAN.” 

The values INF and NAN can 
be read into any of the floating 
point formats, but only if pre- 
ceded by a sign symbol. Thus 
“INF,” “-INF,” “+-NAN,” and 
“-NAN” are considered legitimate 
numbers to scanf(). In the case of 
NAN, the sign is meaningless, ex- 
cept to indicate to scanf() that 
NAN is a number and not a vari- 
able. 


RECOGNIZING INF AND NAN 
Since many situations require spe- 
cial treatment of INF and NAN, 
it’s necessary to be able to recog- 
nize these values when they occur 
in your program. For example, if 
a function returns a NAN, you 
may need to know immediately 
that the function failed. 

Turbo C 2.0 handles +INF and 
-INF correctly in comparisons. 
The following method can deter- 
mine if x equals -INF: 

#define INF (1./0.) 
if (x == INF) ... 

Unfortunately, Turbo C does 
not support comparisons between 
floating point values and NANs. 
This support is not present in 
Turbo C for two reasons. First, 
ANSI C does not require it; and 
second, due to the way that the 
Intel CPU and coprocessor chips 
work, this support could not be 
added without slowing down every 
floating point compare operation. 
Therefore, unless the invalid op- 
eration exception is masked, a 
comparison that involves NANs 
generates the exception and ter- 


x == NAN 
x != NAN 
x < NAN 

x <= NAN 


always TRUE 
always FALSE 
unreliable 
unreliable 


Assume this definition for the above compar- 
isons: #define NAN(0./0.) 


Table 1. Results of comparisons in- 
volving NAN. 


minates the program with the fol- 
lowing message: 


Floating point error: Domain. 


If the INVALID exception is 
masked, the comparison generates 
inconsistent results, as shown in 
Table 1. Therefore, I recommend 
using a procedural test, such as 
the ieee_type() function given in 
Listing 1, in order to determine 
whether or not a number is a 
NAN. 

The function ieee_type() in 
IEEETYPE.C (Listing 1) identifies 
numbers as belonging to one of 
four categories: normal, +INF, 
-INF, and NAN. Zeros, normals, 
unnormals, and denormals are all 
classified as normals for simplicity. 
As long as a prototype can be 
used before ieee_type() is called, 
this function can be used for clas- 
sifying float, double, or long 
double arguments. Because 
ieee_type() requires that long dou- 
bles be in the 10-byte format, this 
function will not work with Turbo 
C versions that are earlier than 


2.0. 


INFINITE PHILOSOPHIES 


Different people have different at- 
titudes towards floating point 
overflows. The traditional (and 
common) view is that debugged 
programs don’t overflow. On 
many mainframes, this may truly 
be the case, because the hardware 
may prevent the program from 
continuing after an overflow oc- 
curs. Therefore, your program 
had better be debugged. In defer- 
ence to this view, the default 
Turbo C behavior is to terminate 
the program in the event of an 
overflow. 

If you share this traditional 
view, Turbo C 2.0 has some new 
features to help you. You can trap 


the overflow, and even though 
you may consider the overflow to 
be fatal, your program can print 
some useful diagnostics before it 
dies. 

The more progressive view is to 
not discriminate against infinities 
and NANs, and to not trap any 
floating point exceptions. This 
view seems more appropriate for 
C programs. After all, C is the lan- 
guage that assumes that the pro- 
grammer knows what to do and 
then lets the programmer do it. 

Currently, Turbo C 2.0 library 
functions such as exp() will not re- 
turn a value larger than 1.8e+308. 
Tradition requires Turbo C to re- 
turn representable numbers, and 
1.8e+308 is the largest such num- 
ber. If the answer should be larg- 
er, then matherr() is called to no- 
tify the programmer of the error. 
However, the new IEEE standard 
has caused people to become 
more broadminded about the def- 
inition of a number—now a num- 
ber can be INF, or even NAN. 
The latest ANSI C draft allows 
these special numbers to be con- 
sidered representable. 

In keeping with this trend, 
some future Turbo C release will 
probably assume that C program- 
mers are ready to play as fast and 
loose with floating point numbers 
as they currently do with pointers 
and other data types. INFs and 
NANs will be declared represent- 
able numbers, just as the ANSI C 
draft allows. When exp(1le10) is 
called, it will just return +INF, 
and possibly not even call math- 
err(). A call to sqrt(-1) might just 
return NAN. 

In the meantime, the same 
thing can be accomplished under 
Turbo C 2.0 by replacing the li- 
brary’s matherr() with a matherr() 
of your own devising, and then 
modifying the variable _huge_- 
dble. _huge_dble occurs in 
<imath.h> in the following con- 
text: 


#def ine HUGE_VAL 


The purpose of _huge_dble is to 
contain the largest representable 
value for programs that need this 
variable. The library functions 
that need this value must simply 
reference _huge_dble. The default 
is 1.8e+308. This value can also 
be defined as +INF. (Turbo C 1.0 


_huge_dble 
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and 1.5 used a function called 
~huge_val() for HUGE_VAL.) 

If you include MATHERR.C 
(Listing 2) in your program, and 
call startfp() when the program 
first runs, then all exceptions 
other than the denormal excep- 
tion are masked, all library errors 
are ignored, and the library func- 
tions return INF under appro- 
priate circumstances. 


CONTINUED FRACTIONS 
Here is a typical example where 
arithmetic with infinities is useful, 
even when a finite result is being 
calculated. Consider the following 
formula: 


tan x = x 


The formula converges to 
tan(x) for any value of x. This 
type of formula is called a con- 
tinued fraction, and can be thought 
of as being analogous to a power 
series. In this case, the continued 
fraction can be more useful for 
approximating the tangent of x 
since the formula converges ev- 
erywhere, and converges more 
rapidly than the power series. 
(The power series is only good for 
|x| < 7/2, as the tangent function 
has a singularity at 7/2.) 

The code in TAN.C (Listing 3) 
uses long doubles for interme- 
diate results. The calculation is 
likely to lose only a couple of bits 
of long double precision due to 
roundoff error, which won’t mat- 
ter once the calculation is round- 
ed again to double precision. 
Thus, an answer will be accurate 
to the limits of double precision. 

The nice thing about this exam- 
ple is that infinities can occur in 
the calculation, yet it always gives 
the correct finite answer if 
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FLOATING POINT 
continued from page 71 


enough terms are used. In fact, 
because of the way the calculation 
is coded, it divides by 0 the first 
time through the loop! 

Not all calculations are so for- 
tunate. If a calculation produces 
an infinity, there’s the risk that a 
0*INF, INF-INF, or INF/INF 
might produce a NAN. (0/0 also 
produces a NAN.) Any calculation 
that depends upon a NAN yields 
a NAN. If the introduction of a 
NAN into a calculation is a possi- 
bility, then the calculation must 
check the result to see if the result 
is a NAN, or if the invalid bit was 
set in _status87(). For example, 
consider the following expression: 
_Status87() & 

(SW_INVALID | SW_ZERODIVIDE | 

SW_OVERFLOW) 
If this expression evaluates to a 
nonzero value, then an invalid op- 
eration, a divide by zero, or an 
overflow must have occurred after 
either the start of the program or 
the last call to _clear87() or _fpre- 
set(). Arithmetic operations on 
NANs are considered invalid 
operations. 

Note that approx_tan() treats 
x = 0 as a special case. If this were 
not so, then approx_tan() would 
encounter 0/0 and return a NAN. 
A better fix for this problem is to 
initialize y with some nonzero 
value. 


USING signal() TO TRAP 
EXCEPTIONS 


ANSI C specifies a portable way to 
trap floating point exceptions. 
This method involves using the 
signal() function to install a float- 
ing point exception handler. Tur- 
bo C 2.0 fully supports this 
scheme, as shown in SIGTEST.C 
(Listing 4). 

Call signal(SIGFPE,fphandler) 
to install the handler, and call 
setjmp(jump1) before doing any 
floating point calculations. Every 
time the handler is triggered, it 
must reinstall itself, because each 
signal causes the main program to 
revert to its default signal handler. 
(This is an old UNIX quirk.) 

Following are the reasonable al- 
ternatives for a floating point ex- 
ception handler. Items 3 and 4 re- 
quire a physical coprocessor. 


1. Print a suitable error message 
and exit (this is the process per- 
formed by the default handler). 
A program that wants to do the 
same thing may still wish to re- 
place the handler in order to 
do some additional house- 
cleaning or to print a more in- 
formative error message. 

2. Perform a long jump to a safe 
place in the program. If this is 
done, the program must pay at- 
tention to all of the usual haz- 
ards of long jumps. In addi- 
tion, the program should call 
_fpreset() to reset the coproces- 
sor or emulator. (The library 
function _fpreset() resets the 
coprocessor. If for some reason 
a special value is maintained 
for the 8087 control word, then 
the control word must be reset 
to that special value because 
_fpreset() installs the default 
Turbo C control word.) Since 
interrupts occur asynchro- 
nously, there is more than the 
usual danger here that an in- 
terrupt will happen while the 
code is in an inconsistent state. 

3. Set a flag and continue. As with 
case 3, most programs may pre- 
fer the simpler strategy of 
masking the exceptions. The 
occurrence of the exception 
can still be detected by exam- 
ining the status word with 
_status87(). The status word 
can then be cleared with 
_clear87(). 

4. Attempt to analyze the damage 
and repair it. This is nearly im- 
possible, because the 8087 is a 
very complex chip with many 
instructions, data types, regis- 
ters, and special cases. How- 
ever, the Turbo C Runtime Li- 
brary Source does include a C 
interface to handle floating 
point exceptions, in which 
some additional information is 
provided. 

Anyone who traps exceptions 
should be aware that some ver- 
sions of DOS 3.2 contain a rather 
nasty bug, where DOS only allows 
eight exceptions before it halts the 
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machine. Microsoft has a patch 
that fixes the problem. If you are 
using DOS 3.2 and a coprocessor, 
I strongly recommend that you 
either obtain the patch or else 
switch to DOS 3.1 or 3.3. 


R.I.P. UNARY PLUS 


As described in my earlier article 
on Turbo C floating point, the 
ANSI C draft had proposed a una- 
ry plus sign to force expressions 
to be evaluated in a particular 
order. This was needed by numer- 
ical analysts because C compilers 
traditionally reserve the right to 
ignore parentheses in an expres- 
sion such as the following: 


x = Cy ~ 2.1) 2 Ze 


Turbo C 1.0 and 1.5 supported 
a unary plus to force a particular 
order of expression evaluation. At 
the ANSI C meeting in December 
1987, however, the decision was 
made that compilers should al- 
ways evaluate parenthesized ex- 
pressions first, unless it’s provable 
that the expression evaluation 
order doesn’t make any differ- 
ence. Turbo C 2.0 supports this 
change. Thus, the unary plus is 
obsolete in Turbo G, yet still sup- 
ported. 


MAKING POINTS 

The C language is becoming in- 
creasingly popular for numerical 
work. Its old defects (such as re- 
arranging parenthesized expres- 
sions and not type-checking func- 
tion arguments) are no longer 
present. Turbo C now has features 
that FORTRAN programmers can 
only dream about: extended pre- 
cision, trappable exceptions, INF, 
and NAN. These, along with all of 
the usual advantages of C (porta- 
bility, preprocessor, dynamic 
memory, convenient data types, 
and control structures) and the 
advantages of Turbo C (speed, in- 
tegrated environment, third- 
party support) make Turbo C the 
language of choice for nearly all 
numerical tasks. 


Roger Schlafly is in charge of scientific 
and engineering products at Borland. 
He is the author of Eureka: The 
Solver and worked on floating point 
support for Turbo C. 


Listings may be downloaded from 
Library I of CompuServe forum 
BPROGB, as CFLT20.ARC. 


LISTING 1: TEEETYPE.C 


enum ieee ( 
ieee_normal, 
jeee_pINF, 
jeee_mINF, 
jeee_NAN, 


ieee ieee_type(long double x) 


unsigned int *a = (unsigned int *) &x; 

if ((al4] & Ox7FFF) != Ox7FFF) return ieee_normal; 

if (a0) | aft) | af2) | (af3] & Ox7FFF)) return ieee_NAN; 
return a[4] & 0x8000 ? ieee_mINF : ieee_pINF; 


LISTING 2: MATHERR.C 


#include <math.h> 
#include <float.h> 


#define INF (1./0.) 
define NAN (0./0.) 


void startfp(void) 

r¢ 
/* mask all exceptions but denormal */ 
_control87(MCW_EM-EM_DENORMAL ,MCW_EM); 
HUGE_VAL = +INF; 

> 


/* this gets called by library functions 

if a domain or range error occurs 
ps A 
int cdecl matherr(struct exception *e) 
€ 
/* return nonzero to show error has been handled */ 
/* Lib functions will return something sensible, */ 
/* if you let them */ 
/* we don't need no steenkeen' errors! */ 

return 1; 

> 


LISTING 3: TAN.C_ 


#defime NUM_TERMS 15 
double approx_tan(double x) 
€ 
int 4: 
long double x2 = x*x, y = 0; 
if (x == 0) return 0; 
for (i = 2*NUM_TERMS-1; i >= 
¥ = l= x2 sy: 
return x / y; 
> 


/* for _control87 */ 
#include <float.h> 
/* for tan */ 
#include <math.h> 


int cdecl main(int argc, char **argv) 
€ 
double x, y; 
/* mask all exceptions but denormal */ 
_control87(MCW_EM-EM_DENORMAL ,MCW_EM); 
Xx = 2.1 
y = tan(x); 
printf("tan(%g) = %25.20g\n",x,y); 
y = approx_tan(x); 
printf("approx_tan(%g) = %25.20g\n",x,y); 


LISTING 4: SIGTEST.C 


#include <signal .h> 
#include <stdio.h> 
#include <stdlib.h> 
#include <set jmp.h> 


extern jmp_buf jump1; 


void cdecl fphandler(int sig) 
€ 
fprintf(stderr,"Floating point error.\n"); 
/* clean off the chip */ 
_fpreset(); 
/* reinstall the exception handler */ 
signal (SIGFPE, fphandler); 
/* jump to a safe place */ 
Long jmp¢ jump!) ; 
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TURBO C 


A DIRECTORY SEARCH 
ENGINE IN TURBO C 


Here’s a truly generalized directory 
search routine that calls a procedural parameter 
each time it finds a matching file. 


Jake Richter 


DOS would not have made it very far 
without the ability to use wildcard charac- 
ters for certain file operations, such as 
COPY, DIR, and ERASE. Imagine copying 
all 142 of your C source code files from 
your hard disk to a floppy disk by typing 
their names on the DOS command line, one at a 
time. The means to avoid this sort of mindless 
drudgery are the low-level DOS functions Find First 
and Find Next. 

Find First searches for the first occurrence of a 
given file specification in a specified directory. The 
file specification may contain the wildcard characters 
“se” and “?,” and thus can match more than one file. 
Find Next simply attempts to locate the next occur- 
rence of the same file spec, and can be called repeat- 
edly until no more matching files are found. Find 
First and Find Next comprise DOS’s built-in file 
search toolkit. In this article, we’ll examine the work- 
ings of Find First and Find Next, and will build them 
into a generalized file search “engine” for use with 
Turbo C. (On page 26 of this issue, Neil Rubenking 
implements a file search engine under Turbo Pascal 
5.0, also using Find First and Find Next.) 


ENTER THE DTA 

Under DOS 2.x and later, Find First and Find Next 
are implemented as DOS functions 4EH and 4FH, 
respectively. Both functions require that a filename 
template (with optional path) and a file attribute 
value be specified. Using Find First and Find Next 
also requires the use of the DOS Disk Transfer 
Area (DTA). 

The Disk Transfer Area is used by DOS for exactly 
what its name implies: Disk data is transferred to and 
from this area of memory. When Find First and Find 
Next are called, the information returned by DOS is 
placed into the DTA. When a DOS application first 
starts up, the DTA is set to a 128-byte region at offset 
80H into its Program Segment Prefix (PSP). The 
Program Segment Prefix is a 256-byte block that is allo- 
cated by DOS in memory, in front of a loaded pro- 
gram. The DTA can also be moved to a more con- 


PROGRAMMER 


venient place, such as your program’s data space. 
This move is accomplished by using the DOS func- 
tion Set DTA Address (1AH), which is called through 
DOS interrupt 21H using the following register 
values: 


© AH = IAH Specifies the Set DTA Address 
function 
© DS:DX = Segment:Offset of new DTA 


Function 1AH returns no errors. 

When moving the DTA to your own program 
space, make sure that enough space is allocated for 
whatever DOS operation you plan to use. For the 
Find First and Find Next functions, the minimum 
DTA size is 43 bytes. 


DIRECTORY ENTRIES AND ATTRIBUTES 


When Find First and Find Next find a file, they re- 
turn information in the DTA that comes from the 
found file’s disk directory entry. There are three 
basic types of directory entries: volume labels, subdi- 
rectories, and normal files. Each entry in the direc- 
tory structure uses the same amount of directory 
space. The entry types are differentiated from one 
another by the values in the file attribute field. 

Six file attributes are currently supported by DOS, 
and each file attribute has its own bit flag in the at- 
tribute field. 


Bit 0 (01H): Read-Only. This attribute applies only 
to regular files. When set, it indicates that the file 
cannot be deleted or written to. A subdirectory en- 
try’s Read-Only flag can be set, but the flag doesn’t 
affect the use of that subdirectory. The Read-Only 
flag can be modified by using the ATTRIB program 
under PC-DOS and some versions of MS-DOS. 


Bit 1 (02H): Hidden File. This flag applies to files 
and subdirectories. When it’s set, the file or subdirec- 
tory can’t be seen in a DIR listing, and a hidden file 
can’t be deleted from the command line. However, 
the file can still be accessed by a program, or by 
other DOS utilities such as TYPE or COPY. Hid- 

den subdirectories can be accessed by RMDIR and 
CHDIR. 
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Bit 2 (04H): System File. The System File attribute’s 
effects are similar to those of the Hidden File attri- 
bute. The reason for the existence of the System File 
attribute lies in the DOS boot process. When IBM 
versions of DOS boot up, they search for two hidden 
system files, IBMBIO.SYS and IBMDOS.SYS, which 
are required in order to complete the boot proce- 
dure. 


Bit 3 (O8H): Volume Label. This attribute identifies 
its directory entry as the current volume’s volume 
label. Each DOS volume can only have one valid 
volume label. If multiple directory entries have the 
Volume Label bit set in their attribute fields, then 
only the entry that is listed first in the directory is 
recognized. No other attributes can be set in con- 
junction with this attribute. Once it’s flagged as a 
volume label, the directory entry can only be mod- 
ified by using an extended FCB (as explained in 
“Taking Charge of DOS Volume Labels,” TURBO 
TECHNIX, November/December, 1987). 


Bit 4 (10H): Subdirectory. All subdirectories have 
this flag set in their attribute field. 


Bit 5 (20H): Archive. This flag is set each time a 
file is altered. DOS programs such as BACKUP and 
XCOPY use this bit to perform incremental backups 
(i.e., to back up only those files that have changed 
since the previous backup). When the file is copied 
by these utilities, its Archive flag is cleared; the flag 
remains clear until it’s set again by a subsequent 
modification. The Archive flag has no effect on sub- 
directories. Like the Read-Only flag, the Archive flag 
can be modified by the ATTRIB program. 


DOS FUNCTION 4EH 

The DOS Find First function is called via INT 21H 

by using the following register protocol: 

e AH = 4EH 

© CX = File attribute 

© DS:DX = Segment:Offset of ASCIIZ pathname 
string 

Here are some things to keep in mind when setting 

up and using Find First. 


1. The DTA must have been previously set to a buffer 
that contains at least 43 bytes of free memory. 


2. The file attribute parameter specifies which file at- 
tributes must be present in order for a match to be 
legal. Four attributes are valid when using Find 
First: Hidden File, System File, Volume Label, and 
Subdirectory. If no attribute bits are specified, reg- 
ular files (those with no attribute set) are searched 
for, as well as those files whose Archive or Read- 
Only attributes are set. If only the Volume Label at- 
tribute is set, then only a volume label is searched 
for. 


3. The ASCIIZ string can contain both a path and 
the file specification. The file specification can 
consist of a combination of valid characters and 
the two wildcard characters, “*” and “?.” 

If the Carry flag is set upon return from Find First, 
then one of the following errors occurred in the 
code returned in AX: 


@ File not found—02H 
® Path not found—03H 
® No more files/No match found—12H 
If the Carry flag is not set, then no error occurred 
and the DTA contains the information returned by 
this call. In essence, if DOS reports an error on Find 
First or Find Next, then there are no more files to be 
found (assuming that you’ve previously validated the 
file path). 

The information returned by DOS is placed in the 
DTA, and can be represented by the C structure 
shown in Figure 1. 


struct ffblk 
€ 


char ff_reserved[21]; /* Reserved by DOS.*/ 
char ff_attrib; /* Attribute found.*/ 
int ff_ftime; /* File time. ei. 
int ff_fdate; /* File date. =f 
long ff_fsize; /* File size. tif 
char ff_fname[13]; /* Found file name.*/ 
3; 


Figure 1. A C structure to divide the DTA into named fields. 


The ffblk structure is defined by Turbo C in the 
DIR.H include file. The ff_reserved field is used by 
DOS to store information pertinent to the search, 
such as current index into search, search mask, and 
so forth. The ff_fname field is an ASCIIZ string that 
contains the name of the file that was just found by 
Find First (and Find Next), with all spaces removed 
and a “.” added to separate the filename and exten- 
sion. ff_attrib, ff_ftime, ff_fdate, and ff_fsize are the 
attribute, the time and date of last update, and the 
size of the found file, respectively. 

Certain constant definitions in Turbo C’s DOS.H 
file can help break down the ff_attrib field into its 
individual bit flags. The definitions and their mean- 
ings are summarized in Table 1. 

Turbo C implements a function that calls Find 
First as findfirst(); the function definition is shown 
in Figure 2. findfirst() returns a nonzero value if no 
files that match the filename are found. The Turbo 
C version of the call requires a pointer to an ffblk 
structure because Turbo C sets the DTA to the spec- 
ified ffblk structure, prior to calling the DOS-level 
Find First. This approach is very useful when several 
ffblk structures are active at the same time, as I'll de- 
scribe shortly. 


CONSTANT VALUE MEANING 
FA_RDONLY 0x01 Read-Only 
FA_HIDDEN 0x02 Hidden File 
FA_SYSTEM 0x04 System File 
FA_LABEL 0x08 Volume Label 
FA_DIREC 0x10 Directory 
FA_ARCH 0x20 Archive 


Table 1. Predefined constants in DOS.H that specify indi- 
vidual bit flags in the file attribute byte. 


DOS FUNCTION 4FH 


The DOS Find Next function is also called via INT 
21H, with register AH set to 4FH. No other registers 
need to be set. As its name implies, Find Next re- 


continued on page 76 


September/October 1988 TURBO TECHNIX 75 


SEARCH ENGINE 
continued from page 75 


#include <dir.h> 
#include <dos.h> 
typedef FFBLK struct ffblk; 


int findfirst(filename, ffblkPtr, attrib) 

char *filename; /* File mask w/optional path */ 
FFBLK *ffblkPtr; /* Pointer to an ffblk struct */ 
int attrib; /* Valid attributes for search */ 


/* For cleaner decl.*/ 


Figure 2. Function findfirst() and its associated 
definitions. 


quires a DTA that has been initialized by a Find First 
call. (Without a properly initialized DTA, DOS won't 
know what file spec or attribute to search for, nor 
even where to start looking.) When it locates an ad- 
ditional match, Find Next updates the information in 
the DTA. 

If the Carry flag is set upon return from the Find 
Next call, then either error code 02H (file not found) 
or 12H (no more files found) is returned in AX. If 
the Carry flag is cleared, then no error has occurred. 

In Turbo C, Find Next is accessed through library 
function findnext(), which is defined as shown in 
Figure 3. As with findfirst(), the value returned by 
the findnext() function is nonzero if no files that 
match the file specification (which is already in the 
DTA) are found. findfirst() and findnext() both use 
the ffblk structure to divide the DTA into fields. 


THE SEARCH ENGINE 


As you may have gathered from the discussion so far, 
the findfirst() and findnext() routines work best in 
combination. They suggest a general-purpose file 
search “engine” that searches a specified directory 
for files that match a given file spec and file attribute 
value. When a file is found, the engine takes some 
action by calling a function that is passed to the en- 
gine through a procedure pointer. I’ve implemented 
such a search engine function as a separate code 
module that can be linked with other Turbo C pro- 
grams. The SearchEngine() function definition is 
given in Figure 4. The actual code for SearchEn- 
gine() can be found in ENGINE.C (Listing 1). 
SearchEngine() takes a file spec (which may in- 
clude a path), an attribute value that specifies which 
file attributes are valid to search for (see the earlier 
explanation of Find First), and a pointer to a proce- 
dure. This procedure is called each time a file that 
matches the file spec and attribute is found. The pro- 
cedure’s definition (assuming that you name the 
function MyFunc()) is as follows: 
#include <dir.h> 
#include <dos.h> 
typedef FFBLK struct ffblk; 


void MyFunc(ptrFFBLK) 
FFBLK *ptrFFBLK; 

If the step of passing a procedure to the search 
engine doesn’t appear useful at first glance, let me 
provide an example. Let’s assume that it’s necessary 
to view the names of all of the current directory’s C 
source code files that have been modified since your 
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#include <dir.h> 

#include <dos.h> 

typedef FFBLK struct ffblk; 

int findnext(ffblkPtr) 

FFBLK *ffblkPtr; /* Pointer to an ffblk struct */ 


Figure 3. Function findnext() and its associated definitions. 


#include <dos.h> 


void 
char 
char 
void 


SearchEngine(filename, attribute, procPtr) 
*fi lename; 

attribute; 

(*procPtr)(); 


Figure 4. Function SearchEngine() and its associated 
definitions. 

last backup. The code for this task is provided in 
MODIF-C.C (Listing 2). 

MODIF-C contains two routines, main() and Dis- 
playModC(). main() serves as the program entry 
point, and initiates the call to SearchEngine(). Note 
that SearchEngine() is passed a file spec that con- 
tains a wildcard character “*” as the filename, with 
the extension fixed as “C.” The attribute that is 
passed is “0,” which indicates that only plain files are 
valid (Read-Only and Archive attributes are consid- 
ered plain for our purposes). Also, a pointer is 
passed to DisplayModC() so that SearchEngine() can 
call DisplayModC() on each “hit” during the search. 

Note that the function called by SearchEngine() 
has complete access to the found file’s directory in- 
formation, via the pointer to the found file’s DTA. 
This means that the file’s name, date, time, size, and 
attribute are available to the procedure called 
through the procedure pointer. If necessary, the di- 
rectory for the file can be determined by making a 
call to the Turbo C library function, getewd() (Get 
Current Working Directory), as I'll demonstrate later. 

To re-create MODIF-C.EXE with the command- 
line Turbo C compiler, execute the following DOS 
command-line commands: 
tec -c modif-c.c 
tcc -c engine.c 
tcc modif-c.obj engine.obj 
The -c option indicates that only an object file 
should be produced for the given source code file. 
The last line specifies that the two object code files 
are to be linked into an executable file. The .PRJ file 
that creates MODIF-C.EXE using the Turbo C Inte- 
grated Development Environment contains just two 
lines: 
modi f-c 
engine 


SEARCHING A DIRECTORY TREE 


Let’s go one step further than the previous example, 
and say that we want to display the names of all of 
the modified C source code files that are located any- 
where on the current drive, even though these files 
might be in different subdirectories. This is not an 
easy problem to solve with typical iterative program- 
ming methods. Fortunately, this kind of problem is 
easy to solve by using recursion. 


B 
ee 
E F 
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ent K 


Figure 5. A schematic of a directory tree. 


First, a warning to those who aren’t familiar with 
recursive techniques: Recursion is not free. Its cost is 
stack space. Every time a call is made, stack space is 
used to save the return address. If parameters are 
passed to a function, the parameters are placed on 
the stack as well. Finally, if local variables are de- 
clared within a function, those variables are also al- 
located on the stack. 

As you might know, the stack is limited in size. In 
the case of the PC, the maximum stack size is 64K 
(usually, however, the size limit is far less). Based on 
this, a tradeoff can be made between greater nesting 
depth versus a greater number of parameter and 
local variables when you design a function. 

If the stack size is exceeded, then critical data or 
code may be overwritten, crashing the application or 
even the system. This condition is known as stack 
overflow. Turbo C lets you guard against stack over- 
flow to some extent by using the -N switch on the 
command-line version of the compiler. Unfortu- 
nately, -N will not always work, especially if inline as- 
sembler code is used to manipulate the stack. Also, 
-N adds overhead in terms of execution speed and 
executable code size. ’'d recommend using -N only 
for debugging recursive routines; eliminate it once 
the routine has been thoroughly shaken out. 

In the case of Small model Turbo C code, each 
call requires four bytes of stack. Local variables re- 
quire two bytes or more per variable. (The precise 
number of bytes depends upon a variable’s type; use 
sizeof() to determine the variable’s size.) Each pa- 
rameter requires at least two bytes (again, the num- 
ber of bytes depends upon the parameter’s type). 
The amount of stack space available in the Small 
model depends upon the amount of space used by 
your global and static data. 


RECURSIVE SEARCHES 


DIRTREE.C (Listing 3) implements a routine that 
performs a recursive tree search of a directory tree, 
starting at the current directory. DIRTREE uses two 
routines, DirTree() and GetNextDir(). DirTree() is 
the entry point for the module. In addition, Dir- 
Tree() cuts down on stack overhead by initializing 
static variables that are used by the recursive routine, 
GetNextDir(). Since GetNextDir() has no param- 
eters and no local variables (it uses static variables 
instead), the only stack overhead incurred at each 
nesting level is the call data, which amounts to four 
bytes for the Small model. 


The prime directive when designing recursive rou- 
tines is to build in a fail-safe mechanism that termi- 
nates recursion at some point. Any one of the follow- 
ing three conditions terminates recursive calls to 
GetNextDir(): 


1. The current directory has no subdirectories; 


2. All of the subdirectories of the current directory 
have already been searched; or 


3. The nesting depth exceeds the maximum depth 
of the algorithm. GetNextDir() currently handles 

a maximum directory tree depth of 15 levels; this 

value can be changed. (The only reason for its 

current setting is that I consider 15 levels to be 

an extreme depth that virtually no one would 

require.) 
Note that conditions 1 and 2 are normal terminators, 
while 3 is an error condition. 

Each level of recursion (and, hence, each direc- 
tory to be searched) has its own FFBLK structure. 
This is necessary in order to determine whether ter- 
minating condition #2 (as given above) has oc- 
curred. The DTA for a specific search contains a 
place marker that DOS uses to determine the starting 
position for Find Next. Therefore, DOS knows when 
its search on any given directory is complete. This al- 
lows the transparent use of findfirst() and findnext() 
in a recursive directory tree search, as long as a 
pointer is passed to the correct FFBLK structure for 
any given level. 

The association of each level of recursion with its 
own FFBLK is performed by declaring an array of 
FFBLK structures named fileBlock. The number of 
elements in fileBlock is given by the constant MAX- 
DIRDEPTH (which, at 15, allows more nesting levels 
than anyone is ever likely to encounter). A variable 
named curDepth acts as the index into the array of 
FFBLK structures. Each successive call to GetNext- 
Dir() increments curDepth, and each return from 
GetNextDir() decrements it. 

If the FFBLK structures were declared as local to 
GetNextDir(), DirTree() would be significantly sim- 
plified, since as the array and its index would no 
longer be required. Each recursive level’s FFBLK 
would be created on the stack when each recursive 
call is instantiated, and the different FFBLK struc- 
tures would never get mixed up. This method, how- 
ever, uses a great deal more stack space, and the aim 
here is to use as little stack space as possible. 

Turbo C’s findfirst() and findnext() also make it 
convenient to integrate the recursive directory 
search routine GetNextDir() with SearchEngine(). 
Each time a normal terminating condition is en- 
countered, a call is made to SearchEngine(). The 
normal terminating conditions are designed such 
that each directory in a tree causes only one termi- 
nating condition. As an example, consider Figure 5, 
which schematically shows a directory tree whose 
root is a directory named “A.” 

When called to process the subdirectories in Fig- 
ure 5, SearchEngine() processes them in the follow- 
ing order: E, I, F, J, K, G, B, C, H, D, and A. Sub- 
directories E, I, J, K, C, and H cause termination 
condition #1 (notice that they have no child directo- 
ries). The rest of the subdirectories cause condition 


continued on page 78 


September/October 1988 TURBO TECHNIX 77 


LISTING 1: ENGINE.C 


[PRRERAAAEREERERRRAEEAREREORERERERREREREREREEREERAERRERE ERED 
ENGINE.C - by Jake Richter 


Provides core routine for a search engine that searches 
the current directory for a given file name (which may 
contain wildcards) with specific attributes. When a file is 
found, the engine calls a function whose pointer it is 
passed upon entry with the contents of the DTA returned by 
the Find First and Find Next functions. 
RERRAEEARAERRAARERARERRRRE EER REREREREREERERREREEERERRERREERE / 
#include "dos.h" /* Contains ffblk structure. * 
#include "dir.h" /* Required by findfirst, findnext, 

getcwd. =! 


[PRERRERARRERAERARERERAEREREERERREREEREDREEERENERERERRERRERRE 
Program Definitions 

RREAAARARRAREREERERERREERERERRERRREREREERERERREERERERERERERE / 

tidef ine FALSE 0 

#define TRUE 1 FALSE 

typedef struct ffblk FFBLK; 


[RRHEARERRAAARERRRERERERERE EAE ERERERERREREEEREREEER ER EREREEER 

Mandatory Global Declarations 
RERRRRRRRRAEARERERARRRERRRAER ER RR RERERREREEERRRERERRREORRERES / 
static FFBLK procBlock; /* Declare a file info block 
for the specific procs.*/ 


[PRRARRARRERERERERREREREEAERARRERERAREERERERERERERREREREER EEE 
void SearchEngine(filename, attribute, procPtr) 


This routine sets up the call for the recursive tree 
search routine and the search engine. 
REARARARARAARAARRRRRREREARERERRERERERRER ERR RERERRRA ER EERE / 
void SearchEngine(filename, attribute, procPtr) 
char *filename; 
char attribute; 
void (*procPtr)(); 
€ 


done; 


done = findfirst(filename, &procBlock, attribute); 
/* While there are still matching files... 
while (!done) 
" 


(*procPtr)(&procBlock); /* Call the user's function. 
done = findnext(&procBlock); /* Search again. 
d 

return; 


LISTING 2: MODIF-C.C 


[RRRRRAAAAREARREREARERERANERERARRARERERERERRERERRER ERR ERER ERE 
MODIF-C.C - by Jake Richter 


Displays all C source files in the current directory 
that have their archive bits set. 


RARRERERARRRARERRRRERERARRRREEER ARR REE REAR ERERERERERRER AED / 
#include <stdio.h> 

#include <dos.h> 

#include <dir.h> 


[PRAARAERRARAREERAAREERRAERARERERAEREEREREREEERRERRRRRREEEEEE 
Program Definitions 

ERARARAERARRERRER ERR RERERERERERERERERE EERE ERE ER ERERERERRERE / 

tdefine FALSE 0 

define TRUE 1 FALSE 

typedef struct ffblk FFBLK; 


[PRRRRRRAARERAARRAR RARER RR ARR ERR ERRERER EERE EERRRRE EERE REE 


Externals 
RRRERARRRERRERERARERERRREREREREERRERERRERRERRERRERERREREREREE / 


extern void SearchEngine(); 


[ERAS AIRE RRR RII IAI IIIA IIIS ISIII SESS ISS ISISI A. 


void DisplayModC() 


This routine is called once for every C source file 
in the current directory. It displays only those C files that 
have their Archive attribute bit set. 
RRRRERARRRERRARR RAR ERRERERERREREERERERRER ERA RRRE EERE ARERR / 
void DisplayModC(searchRec) 
FFBLK *searchRec; 
€ 


if (searchRec->ff_attrib & FA_ARCH) 
printf("%s\n", searchRec->ff_name); 


return; 
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SEARCH ENGINE 
continued from page 77 


#92 after all of their child directories have been 
searched. 


TWO ENGINES 


What we now have are two different routines, both 
of which are general-purpose search engines for 
DOS directories. SearchEngine() searches a single di- 
rectory, and DirTree() searches the entire directory 
tree of the current drive. Use whichever routine is 
appropriate; their parameter lists are identical. 

For example, to incorporate full recursive tree 
search into the simple MODIF-C demo program, just 
substitute the following line for the original call to 
SearchEngine(): 

DirTree("*.C", 0, DisplayModC); 


Then recompile DIRTREE.C, recompile MODIF-C.C, 
and link the final .EXE file to the Turbo C com- 
mand-line compiler using the following commands: 
tcc -c dirtree.c 

tcc -c modif-c.c 

tcc modif-c.obj engine.obj dirtree.obj 

If you’re using the Integrated Development Environ- 
ment, the .PRJ file would look like this: 

modi f-c 

engine 

dirtree 

The resulting program, MODIF-C.EXE, finds and 
displays the names of all of the modified C source 
files that are located in the current directory and in 
all of the directories below it. 

To make the interface to the two search engine 
routines clear, MODIF-C has been kept bare-bones 
simple. Your first enhancement should almost cer- 
tainly be to retrieve command-line parameters so 
that the program can be set to search for more than 
just C source code files. [Editor’s note: In future 
issues of TURBO TECHNIX, we'll publish short arti- 
cles that present file utilities built around the search 
engines—watch for them.] 


DON’T SOLVE PROBLEMS— BUILD TOOLS! 


Because the search engines’ action is specified by 
the calling logic at runtime through procedure point- 
ers, the search engines can be applied to a variety of 
tasks, such as building linked lists of directory en- 
tries, deleting files, printing file headers, moving files 
out to a backup drive, and so forth. The possibilities 
are virtually unlimited, and need not be specified at 
compile time. That’s the advantage of an “engine” 
concept, as opposed to simply hard-coding fixed so- 
lutions to individual problems. When you solve a 
problem, work a little longer to turn the solution into 
a tool—and you'll work less the next time the prob- 
lem comes up. 


Jake Richter is the President of Panacea, Inc., a PC con- 
sulting company in Woburn, Massachusetts. He can be 
reached on MCI MAIL and on BIX as jrichter. 


Listings may be downloaded from Library I of Compu- 
Serve forum BPROGB, as CENGN.ARC. 


[PPRARARAOARREERRERERAERERREREREREAERREREERREERERERERRERE AREER 
main() 


Here we make the call to SearchEngine. 


RRRRRREREAREREREEARRARERERER ERR RERRERER ERE AR ERE E RARE ERRE / 


main() 
{ 


SearchEngine("*.C", 0, DisplayModC); 
exit (0); 
> 


LISTING 3: DIRTREE.C 


[PRRRRRRR RARER ER RRR AREER ARERR RARER EERE AREER EERE ERERREERS 


DIRTREE.C - by Jake Richter 


Provides core routines for traversing a directory tree, 
using a “bottom-most first" algorithm. 

As presented, code will search the directory tree and 
for each directory found, will call a routine called 
SearchEngine(), which in turn will process certain files in 
that directory in some fashion. 

RERERERERRRRRRRARARA RRR RRRRRRR AREER ERE REE EEREREEERREERRERED 7 
#include "dos.h" /* Contains ffblk structure. ey 
#include "dir.h" /* Required by findfirst, findnext, 

getcwd. 7 


Y hakahahaiainlaiaiaiahataiaieiaiaialalalalaiahalaiahahalelalelaiaiehalslaiaiaishaiaialahaielahsleicieieiaieisisiaiainialel 


Program Definitions 
RAAAAARARAAARAARARERAAARREAAERERAEAAAEARARRREEREREERERRERERED / 
#defime MAXDIRDEPTH 15 /* Maximum directory depth. es 
#define FALSE 0 
#define TRUE 1 FALSE 
typedef struct ffblk FFBLK; 


[ITT ITT TRI ITI IIIA IIIA REE III III IIIS IIIS IA IIASA 


Mandatory Global Declarations 
RARAAREARAAAARAARARARARRARRRRAEARERERREREREREEREREEREEEREEER 7 
/* Declare a file info block 
for each potential 
directory level. bad f 
static fi LeBlock [MAXDIRDEPTH) ; 
static curDepth = -1;  /* Depth indicator. */ 
static done; /* Used as a local flag in 
the recursive function. 
Declared globally to 
minimize stack usage 
incurred by recursion. 
/* Filename mask for the 
Search Engine. 
static char attribute; /* Attribute for engine. 
static void (*funcPtr)(); /* Function ptr for engine*/ 


static char *fj lename; 


Y haiheiaialaleiahaiaiaieiaialataieinieiaiateieiahalalaieieiehalaieleiahaialehshebalsheleielaieiaieielalsiaielsisialaieiel 


void GetNextDir() 


This is the recursive routine that traverses the 
directory tree. 
RRARAARAREAEEEREREERERERARREREREREEERAE RARE EER ESER EERE EEE RES / 
static void GetNextDir() 
€ 
curDepth++; /* Every time this code gets called, we go down 
a level in the tree. *} 


/* We can't go too deep because we have only 
so many file block structures. =F 
if (curDepth >= MAXDIRDEPTH) 
return; 


/* Since this section is encountered only when 
going down to a new level, (re)initialize 
the current level's file block by calling 
findfirst. findfirst and findnext return a 
TRUE (non-zero) value when all files in the 
current directory have been "found." A 
separate block is needed for each level 
because previously determined information 
(set by findfirst() and subsequent findnext() 
calls) must be maintained until an entire 
directory level has been searched. bd f 


done = findfirst("*.*", &fileBlock{curDepth), FA_DIREC); 


/* It is important to remember that "." and 
".." are valid directory names, but that 
they also should be ignored while 
traversing the tree. The following 
conditional in psuedo-code: 


while((mot all files have been “found") 
AND (((the currently found file is really a directory) 
AND (this directory starts with ".")) 
OR (this the file is not really a directory))) 
then 
get the information of the next file found and check 
it against the previous conditions. 


‘eA 
whi le(!done 
&& (((fileBlock{curDepth)] .ff_attrib == FA_DIREC) 
&& (fileBlock[curDepth] .ff_name[0) == '.')) 
|| (fileBlock{curDepth].ff_attrib != FA_DIREC))) 
done = findnext(&fi leBlock [curDepth] ); 


/* When we get to this point, one of two 
things must be true: either we are out of 
files, in which case (done == TRUE), or we 
have found the first valid directory name 
in the current directory. bed 

if (!done) 
¢ /* Since we have found a valid directory, go 
to it and repeat the above. +f 
chdir(fileBlock [curDepth] .ff_name); 
GetNextDir(); /* Call this routine again. 
chdir("..");  /* Move back up to the correct directory 
for this level. 
curDepth--; /* Also adjust the depth gauge. 
> 
else 
{ /* There are no valid directories below 
the current one, therefore this one must 
be at the end of a branch and should be 
processed. 


/* Process this directory. 
SearchEngine(filename, attribute, funcPtr); 
return; /* We're done at this level. 
> 


/* Get the information about the next file. 
done = findnext(&fileBlock [curDepth] ); 


/* We are now searching for all other 
directories that might be below the current 
one. ot f 
while (1) 
€ /* This “while” is the same as the previous.*/ 
while (Idone 
&& (((fileBlock{curDepth] .ff_attrib == FA_DIREC) 
&& (fileBlock{curDepth) .ff_name[0] == '.')) 
|| (fileBlock {curDepth].ff_attrib != FA_DIREC))) 
done = findnext(&fileBlock [curDepth] ); 


if (!done) 

€ /* Drop down to the next level. 
chdir( fileBlock [curDepth) . ff_name); 
GetNextDir(); /* Call this routine again. 
chdir(".."); /* Move back up. 
curDepth--; 

/* Prepare for the "while" above. 
done = findnext(&fi leBlock[curDepth) ); 


/* Wo more files to be found. Break out of 
outer loop. * 


/* Process the current directory since all the 
ones below it have already been processed*/ 
SearchEngine(filename, attribute, funcPtr); 
return; /* Bye. hh 
> 


[PARAERRARARRARERAERAEREREERERERAEERERRERREREREER EERE EREREE ES 
void DirTree(fname, attr, proc) 


This routine sets up the call for the recursive tree 

search routine and the search engine. 

RRRRAARRARARAAEA EA ERERREREREARERERRRAER AREER RRREREEREERRERES / 

void DirTree(fname, attr, proc) 

char *fname; 

char attr; 

void (*proc)(); 

{ 
filename = fname; /* Set global variables for Engine.*/ 
attribute = attr; 
funcPtr = proc; 
GetNextDir(); 
return; 


/* Initiate recursive search. 7 
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TURBO PROLOG 


DEFINITE CLAUSE GRAMMARS 
IN TURBO PROLOG 


A parser is only as good as its grammar. 


Barbara Clinger, Ph.D. 


Since microcomputers have become faster 
and contain more memory, producers of 
software are under pressure to create 
friendlier software. If “user friendly” is a 
euphemism for the ability to exchange in- 
ov formation with computers in English, 
then programs need a process to extract key infor- 
mation from the average user’s input. One such pro- 
cess uses a definite clause grammar (DCG). 

The investigation of definite clause grammars is 
the primary purpose of this article. We'll also exam- 
ine parsers as a means to scan and interpret English 
sentences. In addition, two methods of partition- 
ing—simple partitioning, and parsing by difference 
lists—will be explored and compared. Finally, we'll 
examine a simple mathematical expression parser. 


WIZARD 


GRAMMARS 


Languages are built with words; the lexicographic 
level is the dictionary which gives the definition, as 
well as the function, of a word (noun, verb, and so 
on). A language syntax imposes structure upon 
words. In English, phrases and sentences are part of 
the syntactic structure. In a programming language, 
such as Pascal, syntax is often provided through syn- 
tax diagrams. Figure 1 depicts a syntax diagram for 
a Pascal identifier (name). This diagram shows that 
the identifier must begin with a letter and may be 
followed by a combination of letters and digits. 

Grammars provide another method for describing 
a language. A grammar allows a language to be pre- 
cisely described by the use of a specific syntax. One 
popular grammar, called Bacus-Naur Form (BNF), is 
used to define the Turbo Prolog language (see Figure 
2). To see how BNF syntax is read, consider the fol- 
lowing statement: 
::= ( <letter> | _ ) 

{ <letter> | <digit> | _ >* 


<name> 


This statement says that a name consists of a letter 
or an underscore, followed by zero or more repeti- 
tions of a letter, a digit, or an underscore. 
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Identifier 


Figure 1. Syntax diagram for a Pascal identifier (name). 


Letters and digits are also defined in BNF nota- 
tion. As any programmer knows, failure to follow the 
syntax of a language results in the ubiquitous “SYN- 
TAX ERROR” message, and rejection of the program 
by the compiler. A general discussion of BNF syntax 
can be found in Chapter 7 of the Turbo Prolog Tool- 
box Owner’s Handbook. 

Using these simple concepts, I can define a very 
simple context-free grammar. My dictionary consists 
of three nouns (dog, cat, and water) and one verb 
(drinks). The syntax of this language has one rule: A 


<name> = ( <letter> | _ ) 

{ <letter> | <digit>|] _>* 
<name-list> ::= <name> | <name> , <name-list> 
<variable> ::= ( <capital-letter> | _ ) [ <name> ] 
<functor> = <small-letter> [ <name> ] 
<letter> = <small-letter> [ <name> ] 
<small-letter>  ::= a/b z 
<capital-letter> ::= A|B] ... |Z 
<digit> r= O[1] ... |9 


Figure 2. BNF syntax used to describe a subset of the 
Turbo Prolog language. 


sentence takes the form of a noun, followed by a 
verb, followed by a noun. Using BNF notation, this 
grammar is defined as: 

<sentence> <noun> <verb> <noun> 

<noun> dog | cat | water 

<verb> drinks 

In this language, the following are all correct 
sentences: 

dog drinks water 


cat drinks water 
water drinks cat 


The last sentence is correct since it adheres to the 
syntax of a sentence; this sentence emphasizes why 
this grammar is called “context-free.” The next 
higher level of a grammar imposes semantics (the 
meaning of words) on the language, and is beyond 
the scope of this article. 


DCG NOTATION 

A definite clause grammar (DCG) is simply a 
grammar that is expressed as logic 
statements; parsing is the execution of the 
statements. Although I'll use DCGs in 
context-free grammars in this article, keep 
in mind that they can be used for more 
powerful grammars. 

The notation used with a DCG differs 
slightly from the BNF notation used in 
Figure 2. However, the translation between 
the BNF notation and the DCG notation 
(given in Figure 3) is quite simple. For in- 
stance, the DCG notation for the simple 
grammar in the previous example is the 
following: 
sentence --> noun, verb, noun 
noun --> dog 
noun --> cat 


noun --> water 
verb --> drinks 


cra 


“sentence,” “noun,” and “verb” are called nontermi- 
nals. The tokens (also called terminals) are “dog,” 
“cat,” “drinks,” and “water.” 

The beauty of using DCGs to define a grammar is 
that the implementation in definite clause grammars 
follows naturally from the grammar’s English de- 
scription. For instance, the next example 
defines a grammar to parse sentences 
of the following form: 

John likes Mary. 

The man sees a dog. 

Mary likes the dog. 

John eats. 

The grammar for these 
sentences can be described 
in English as listed below: 


© A sentence takes the form 
of a noun phrase, 
followed by a verb phrase. 
© A noun phrase takes 
either the form of a 
determiner (definite 
article) that is followed 
by a noun; or else 
the form of a noun. 


Model: Mr. Byte 


continued on page 82 


TOKEN 
terminals. 


NONTERMINALS 


The dictionary words are called tokens or 


These are words used in the grammar which are not 


terminals; they are given in terms of other 


language elements. 


==> This symbol is the equivalent of the ::= in BNF 
form and is read "takes the form of". 


: The comma is read "followed by". 


Figure 3. The translation between BNF and the DCG notation. 
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© A verb phrase takes either the 
form of a verb that is followed 
by a noun phrase; or else the 
form of a verb. 


Since the DCG form of the 
grammar will be converted into 
executable Prolog predicates, ac- 
ceptable Turbo Prolog names are 
used in the following definitions: 
sentence --> noun_phrase, 

verb_phrase 
noun_phrase --> determiner, noun 
noun_phrase --> noun 
verb_phrase --> verb, noun_phrase 
verb phrase --> verb 
These definitions, along with the 
dictionary and a mechanism to 
convert DCGs into executable 
Turbo Prolog predicates, parse 
sentences of the desired form. 

There is one more point to note 
in this example. Since these def- 
initions will be converted to exe- 
cutable predicates, the order in 
which the definitions are listed 
can be very important. For in- 
stance, defining the verb phrase 
before defining the noun phrase 
does not affect the outcome in the 
example. However, if the two verb 
phrase definitions are inter- 
changed, then the outcome is 
drastically changed. I'll say more 
about this later in the section on 
difference lists. 


SCANNING AND PARSING 


A parser has two components: the 
“reader” and the “tester.” The 
reader (also called the scanner) ac- 
cepts a stream of input and pro- 
cesses it into the appropriate data 
structure, which is then given to 
the ester. If the tester determines 
that the input is acceptable, it 
passes the information to the in- 
terpreter, which is the portion of 
the program that acts upon the 
information. 


Before we can implement a 
DCG, we must decide upon the 
form of the data that goes into 
and comes out of the parser. The 
decision to use a list of tokens as 
input is almost universal. There- 
fore, the reader’s output should 
consist of a list of tokens to be 
parsed. XPARS.SCA in the Turbo 
Prolog Toolbox is an example of 
a reader that’s designed for input 
into predicates produced by the 
parser generator. The predicate 
reader in Listing 1 produces a list 
of strings that are used as tokens 
in that program. 

Before the parser can be imple- 
mented, the form of the data 
that’s required by the rest of the 
program must be known. The out- 
put can be as trivial as a true or a 
false to indicate that the parsing 
was successful or unsuccessful, re- 
spectively (as shown in Listing 1). 
Alternatively, the output can be a 
list of keywords, a numerical 
value, or a more complicated 
structure that represents a parse 
tree. 

A parse tree is a structure that 
shows the overall construction of 
the original source input. In 
Pascal, the implementation of a 
tree structure is accomplished 
through pointers and records, 
where a record contains some in- 
formation along with pointers to 
other nodes in the tree. In Turbo 
Prolog, a tree structure is repre- 
sented through the use of com- 
pound objects. For instance, the 
sentence “the man sees a dog” 
can be represented by the follow- 
ing Turbo Prolog structure: 
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sentence(noun_phrase( 
determiner(the), 
noun(man)), 
verb_phrase(verb(sees), 
noun_phrase(determiner(a), 
noun(dog)))). 

Figure 4 shows the parse tree for 

this sentence. 

With this sentence structure as 
output, the appropriate predicates 
must be written to extract the in- 
formation from the tree and then 
evaluate that information. Recall 
the DCG for the sentence struc- 
ture: 


sentence --> noun_phrase,verb_phrase 


The translation of this DCG re- 
quires the input list to be parti- 
tioned into two sublists A and B, 
in such a way that the list A is a 
noun phrase and the list B is a 
verb phrase. To see this clearly, 
consider the following input list: 


[the, man, sees, a, dog] 


This list can be partitioned into 
the sublists: 

(the, man] 

[sees, a, dog] 

The next step is to test whether 
the sublists [the, man] and [sees, 
a, dog] satisfy the criteria of being 
a noun phrase and a verb phrase, 
respectively. 

A very simplistic method for 
partitioning the input list is to use 
the predicate append. This two- 
way predicate not only appends 
two lists to produce a third, but it 
can also return all of the parti- 
tions of a list as two sublists. In 
simple grammars (such as the 
grammar implemented in Listing 
1), append is adequate for the job, 
and uses less stack than does the 
difference list method (which is 
described shortly). In a more com- 
plicated grammar, append re- 
quires a lot of backtracking and is 
less efficient. 


DIFFERENCE LISTS 


A more efficient method of parti- 
tioning is based upon an incom- 
plete data structure called the dif- 
ference list. This alternative to list 
processing can greatly simplify 
list-processing programs. 

In order to use this partitioning 
method, a “subtraction” between 
two lists must first be defined. 
Let’s examine the list A = [a, b, c]. 
A can be considered, in many 
ways, to be the difference of two 


sets, such as in the following 
examples: 


[a,b,c] = [a,b,c,d,e] - [d,el, 
[a,b,c] = [a,b,c,d] - [d] 
{a,b,c} =" [a,b ck = fi. 


In fact, the following statement is 
true for any set T, where the arbi- 
trary T makes the data structure 
incomplete: 

[a,b,c] = [a,b,c|T] - T, 


In general, if A = [a,b, ... ,d], then 
A is the difference between the 
list X = [a,b, ... ,d|T] and T, where 
T can be any list; this difference 
is denoted by A = X - T. Note that 
the empty list [] is expressed as 

To apply difference lists to 
DCGs, let A = [the, man, sees, a, 
dog! T ] and look at the following 
grammar in terms of difference 
lists: 
sentence --> noun phrase, 

verb phrase 

According to this particular 
grammar, the difference list A - T 
is a sentence if A - Y is a noun 
phrase and Y - T is a verb phrase, 
for some list Y. 

To represent this as a Turbo 
Prolog clause, one would like to 
write: 
sentence(A - T):- 


noun_phrase(A - Y), 
verb_phrase(Y - T). 


The minus sign, however, normal- 
ly implies subtraction between real 
numbers. We could define a pred- 
icate, such as difference(X,Y,Z) 
where the difference of X - Y is 
returned in Z, and use difference 
in the clause for sentence. The 
same idea can also be coded with 
two arguments as in the following 
clause: 

sentence(A,T):- 

noun_phrase(A,Y), 

verb_phrase(Y,T) 

Keep in mind that the two argu- 
ments in this clause refer to the 
difference lists. 

Listing 2 is similar to Listing 1, 
except that difference lists per- 
form the partitioning process in 
Listing 2. The difference lists are 
handled in the following clauses: 
sentence(List_in,Rest):- 


noun_phrase(List_in,Y), 
verb_phrase(Y,Rest). 


noun_phrase(X,Rest):- 
determiner(X,Y), 
noun(Y,Rest). 


verb_phrase(X,Rest):- 


sentence 


anes 


noun phrase 


verb phrase 


Foe 


determiner 
(the) 


noun 
(man) 


verb 
(sees) 


noun phrase 
determiner noun 
(a) (dog) 


Figure 4. Parse tree for the sentence “the man sees a dog.” 


verb(X,Y), 
noun_phrase(Y,Rest). 


determiner( ["the"|Rest] ,Rest). 


noun( ["man'""|Rest] ,Rest). 


To better visualize the action of 
these clauses, Figure 5 shows the 
CALLs and RETURNs from a 
trace of Listing 2 using List_in = 
[“the”, “man”, “sees”, “a”, “dog”]. 
In particular, look at the first 
CALL to noun_phrase (line 2 in 
Figure 5) and follow the sequence 
to its RETURN (line 6). The call 

is made with the second param- 
eter (Rest) uninstantiated. Upon 
the RETURN, Rest is instantiated 
to the noun phrase (which is sat- 
isfied by List_in - Rest), and to the 
potential verb phrase. 

If the first and third clauses for 
verb_phrase in Listing 2 are inter- 
changed, the parser succeeds as 
soon as the verb “sees” is found, 
which causes the noun phrase 
[“a”, “dog”] to be returned in 
Rest. This means that the parser 
has successfully found an accept- 
able sentence, but that the parser 
did not scan all of List_in. 

The program that uses differ- 
ence lists seems more difficult 
than the program that uses ap- 
pend. Even in such a simple gram- 
mar, however, the difference list 
version saves several calls to 
noun_phrase and verb_phrase. 
The time that’s saved is not no- 
ticeable in a simple grammar. In 
more sophisticated grammars, 
however, the difference in time is 
important. 


PARSING MATHEMATICAL 
EXPRESSIONS 


My final example of the use of 
DCGs scans a mathematical ex- 
pression. This example illustrates 
several points, including how to 
handle a DCG that requires spe- 
cific symbols (such as the arith- 
metic operators “+” or “/”); how 
to handle functions (such as the 
trigonometric functions); and how 
to return information from a scan- 
ner. 

For this example, Listing 3 re- 
turns the numeric value of an ex- 
pression, and Listing 4 returns the 
parse tree of an expression. 

Before defining the DCGs to 
parse an expression, let’s think for 
a moment about the precedence 
of operations. Consider the fol- 
lowing expression: 

2* 3 - 4 + 5*(sin(1.5) + 8°2) + 6/7 


The precedence of operations 
dictates that expressions within 
parentheses are evaluated first, 
then the individual terms that use 
multiplication and division are 
evaluated, and finally, the terms 
are summed. In evaluating such 
an expression, parentheses have 
the highest priority, followed by 
exponentiation, then by multipli- 
cation and division, and finally by 
addition and subtraction. Also, 
sin(1.5) represents a number that 
must be “looked up” before the 
expression inside the parentheses 
can be evaluated. I’ve defined a 
DCG in which the terminals are 
numbers (including pi and func- 
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tions that return numbers), with 
the syntax imposed by the oper- 
ators. The order in which the 
grammar is stated determines the 
priority of the operators. 

The previous expression con- 
tains four terms: 2*3, 4, 5*(sin(1.5) 
+ 8° 2), and 6/7. These terms are 
summed together to give the value 
of the expression. The word 
“sum” is used here because the 
operation of subtraction is math- 
ematically defined in terms of ad- 
dition. Subtraction introduces er- 
ror into some implementations of 
an expression parser that tries to 
evaluate from left to right. When 
a left to right evaluation is needed 
or desired, the safest method is to 
replace the -4 with its mathemat- 
ical equivalence, + (-1)*4. (List- 
ings 3 and 4 perform a right to left 
evaluation.) 

In the following example, to- 
kens that are used specifically 
within the definitions are en- 
closed in brackets in order to dis- 
tinguish terminals from nonter- 
minals. 


expr --> expr, [+], term 
expr --> expr, [-], term 
expr --> term 

term --> term, [*], power 
term --> term, [/], power 


term --> power 


power --> group, [7], power 
power --> group 


group --> [(], expr, [)] 
group --> number 


number --> [+], number 
number --> [-], number 
number --> [sin], group 


number --> [cos], group 


number --> [pi] 
number --> [N]. 

The implementation of this 
grammar (in Listing 3) returns the 
value of an expression. Listing 4 
is an abbreviated version of this 
grammar that returns a structure 
for a parse tree. 

Let’s compare the first clause 
for expr from Listing 3 and List- 
ing 4: 

/* From Listing 3 */ 
expr(X,L1,L2):- 
append(Left, ["+"|Right],L1), 
expr(V1,Left,L2), 
term(V2,Right,L2) 
X = V1 + V2. 


/* From Listing 4 */ 
expr (branch(op("+") ,L_node, 
R_node),L1,L2):- 
append(Left, ("+", |Right],L1), 
expr(L_node,Left,L2), 
term(R_node,Right,L2). 
In both programs, the first argu- 
ment determines the nature of the 
output of the parser, while Ll and 
L2 represent a difference list, 
LI - L2. In both programs, append 
splits the original list (L2) into two 
sublists. The left part of this list is 
sent to expr, which checks if this 
part is an expression; the right 
part of the list is sent to term, 
which checks if this part is a term. 


C"man"" - Nsees'!! = Wau ; "dog] ) 


["sees", "a", "dog"'] ) 


CALL: sentence( ["the","man","sees","a","dog"], _ ) 
CALL: noun_phrase( ["the","man","sees","a","dog"], _ ) 
CALL: determiner(["the","man","sees","a","dog"], _ ) 
RETURN: determiner(["the","man","sees","a","dog"], 
CALL: noun( ["man","sees","a","dog"], _ ) 

RETURN: noun( ["man", "sees", "a", "dog"], ["sees", "a", "dog"] ) 
RETURN: *noun_phrase( ["the", "man", "sees", "a", "dog"], 
CALL: verb_phrase(["sees","a"',"dog"], _ ) 

CALL: verb( ["sees","a","dog"]. _ ) 

RETURN: verb( ["sees", "a", "dog"] , ["a"', "dog] ) 

CALL: noun_phrase(["a","dog"], _ ) 

CALL: determiner(["a","dog"], _ ) 

RETURN: determiner( ["a","dog"] , ["dog"'] ) 

CALL: noun(["dog"], _ ) 

RETURN: noun( ["dog"'] , [] ) 

RETURN: *noun_phrase( ["a","dog"] , [] ) 

RETURN: *verb_phrase(["sees","a","dog"'] , []) 

RETURN: sentence(["the","man","sees","a","dog"] , []) 


Figure 5. A sample trace from the program in Listing 2. 
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In the case of Listing 3, if both 
calls are successful, then the re- 
turn values are added together 
(X = V1 + V2), and the resulting 
value is returned by expr. In the 
case of Listing 4, if both calls are 
successful, then the node branch- 
(op(“+”), L_node, R_node) is re- 
turned, where both L_node and 
R_node have been instantiated 
through calls to term. 

Finally, looking at the hierarchy 
of operations, the tokens (num- 
bers) have highest priority, groups 
(parentheses) have next highest 
priority, and so on up to + and -, 
which have lowest priority. This 
priority order corresponds to the 
DCG form of the parser from bot- 
tom to top. 


TRANSLATORS 


The advantage of using a pre- 
written translator is that the parser 
is generated automatically. The 
disadvantage to this approach is 
the need to use output in a form 
that is determined by the transla- 
tor. For example, XPARS from the 
Turbo Prolog Toolbox illustrates 

a parser for simple algebraic ex- 
pressions. With an input of “2 - 10 
+ 3,” the parser returns the fol- 
lowing structure as its output: 


plus(minus(int(2), int(10)), int(3)). 


The parser generator could be 
modified to customize the output 
for your specific needs, although 
this is not a trivial task. 

In summary, there’s really noth- 
ing mysterious or difficult about 
definite clause grammars. The dif- 
ficulty lies in the translation from 
DCG notation to executable 
Prolog clauses. The process of 
writing your own translator re- 
quires more effort in order to de- 
velop the parser, while the use of 
a utility (such as the parser gener- 
ator from the Turbo Prolog Tool- 
box) requires more effort in order 
to use the output in a specific 


program. @ 


Barbara Clinger is a professor of 
mathematics at Wheaton College in 
Norton, Massachusetts. 


Listings may be downloaded from 


Library 1 of CompuServe forum 
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PolyAWK - The Toolbox Language. 
For C, Pascal, Assembly & BASIC Programmers. 


We call PolyAWK our “toolbox” language 
because it is a general-purpose language that 
can replace a host of specialized tools or pro- 
grams. You will still use your standard language 
(C, Pascal, Assembler or other modular 
language) to develop applications, but you will 
write your own specialized development tools 
and programs with this versatile, simple and 
powerful language. Like thousands of others, 
you will soon find PolyAWK to be an indis- 
pensable part of your toolbox. 


A True Implementation 
Under MS-DOS 


Bell Labs brought the world UNIX and C, and 
now professional programmers are discovering 
AWK. AWK was originally developed for UNIX 
by Alfred Aho, Richard Weinberger & Brian 
Kernighan of Bell Labs. Now PolyAWK gives 
MS-DOS programmers a true implementation 
of this valuable “new” programming tool. 
PolyAWK fully conforms to the AWK standard 
as defined by the original authors in their book, 
The AWK Programming Language. 


A Pattern Matching Language 


PolyAWK is a powerful pattern matching 
language for writing short programs to handle 
common text manipulation and data conver- 
sion tasks, multiple input files, dynamic regular 
expressions, and user-defined functions. A 
PolyAWK program consists of a sequence of 
patterns and actions that tell what to look for 
in the input data and what to do when it's 
found. PolyAWK searches a set of files for lines 
matched by any of the patterns. When a match- 
ing line is found, the corresponding action is 
performed. A pattern can select lines by com- 
binations of regular expressions and com- 
parison operations on strings, numbers, fields, 
variables, and array elements. Actions may per- 
form arbitrary processing on selected lines. The 
action langauge looks like C, but there are no 
declarations, and strings and numbers are built- 
in data types. 


Saves You Time & Effort 


The most compelling reason to use PolyAWK is 
that you can literally accomplish in a few lines 
of code what may take pages in C, Pascal or 
Assembler. Programmers spend a lot of time 
writing code to perform simple, mechanical 
data manipulation — changing the format of 
data, checking its validity, finding items with 
some property, adding up numbers and print- 
ing reports. It is time consuming to have to 
write a special-purpose program in a standard 
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PolyAWK Comes With The 
Definitive 

Book On 

AWK... 


Requires 
MS-DOS 
2.0 or above & 256K RAM. $99 


When you order PolyAWK you receive a copy 
of The AWK Programming ranch e written by 
the authors of the original UNIX-based AWK. 
The book begins with a tutorial that shows how 
easy AWK is to use, followed by a comprehen- 
sive manual. Because PolyAWK is a complete 
implementation of AWK as defined by the 
book’s authors, you will use this book as the 
manual for PolyAWK. 

You can purchase PolyAWK and the book, The 
AWK Programming Language, for $99. If you 
already have the book, you can order PolyAWK 
software only for $85, which is $14 off the 
regular $99 purchase price. (The book serves 
as the User’s Manual, so ed you should 
already have a copy of the book if you are order- 
ing the software only.) 


PolyShell Bonus! 


PolyShell gives you 57 of the most useful UNIX 
commands and utilities under MS-DOS in less 
than 20K. You can still use MS-DOS commands 
at any time and exit or restart PolyShell without 
rebooting. MS-DOS programmers — discover 
what you have been missing! UNIX program- 
mers — switch to MS-DOS painlessly! 
PolyShell and PolyAWK are each $99 when 
ordered separately. Save $50 by ordering the 
PolyShell + PolyAWK combination package for 
$149. Not copy-protected. 


30-Day 
Money Back Guarantee 
Credit Card Orders: 
1-800-547-4000 


Ask for Dept. TTX 
Send Checks and P.O.s To: 
POLYTRON Corporation 
1700 NW 167th Place, Beaverton, OR 97006 
(503) 645-1150 — FAX: (503) 645-4576 


High Quality Software Since 1982 


language like C or Pascal each time such a task 
comes up. With PolyAWK, you can handle such 
tasks with very short programs, often only one 
or two lines long. 


Prototype With PolyAWK, 
Translate To Another Language 


The brevity of expression and convenience of 
operations make PolyAWK valuable for proto- 
typing even large-sized programs. You start 
with a few lines, then refine the program, ex- 
perimenting with designs by trying alternatives 
until you get the desired result. Since programs 
are short, it’s easy to get started and easy to start 
over when experience suggests a different 
direction. PolyAWK has even been used for 
software engineering courses because it’s possi- 
ble to experiment with designs much more 
readily than with larger languages. It’s straight- 
forward to translate a PolyAWK program into 
another language once the design is right. 


Very Concise Code 


Where program development time is more 

important than run time, AWK is hard to beat. 

These AWK characteristics let you write short 

and concise programs: 

¢ The implicit input loop and the pattern-action 
paradigm simplify and often entirely elimi- 
nate control flow. 

* Field splitting parses the most common forms 
of input, while numbers and strings and the 
coercions between them handle the most 
common data types. 

¢ Associate arrays use ordinary strings as the 
index in the array and offer an easy way to 
implement a single-key database. 

¢ Regular expressions are a uniform notation 
for describing patterns of test. 

* Default initialization and the absence of 
declarations shorten programs. 


Large Model 
Implementation 


PolyAWK is a large model implementation and 
can use all of available memory to run big pro- 
grams or read files greater than 64K. 


Math Support 


PolyAWK also includes extensive support for 
math functions such as strings, integers, 
floating point numbers and transcendental 
functions (sin, log, etc.) for scientific applica- 
tions. Conversion between these types is 
automatic and always optimized for speed 
without compromising accuracy. 
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LISTING 1: GRAMMAR.PRO 


/* Simple DCG parser 
Barbara Clinger, 1988 


This program illustrates the expansion of a simple DCG. 
Its vocabulary consists of: 

Nouns: John, Mary, man, dog; 

Determiners: the, a 

verbs: likes, sees 


Sample input: The man sees a dog. 
Output: True or False, for success or failure of parsing. 
sf 


domains 
toklist = string* 


predicates 
reader(string, toklist) 
remove_period(toklist,toklist) 
append(toklist, toklist, toklist) 
do 

/* The grammar */ 

sentence(toklist,toklist, toklist) 
noun_phrase(toklist) 
verb_phrase(toklist) 
determiner(string) 
noun(string) 
verb(string) 

goal 
do. 

clauses 


/* The clause do parses a sentence and returns true or false. Its 


writing is informational only. */ 


do 
nl,write("Enter a sentence --> "), 
readin(S),nl,nl, 
reader(S,List), /* use the reader */ 
write("Output of the reader: ",List),nl,nl, 
remove _period(List, List_in), 
sentence(List_in,Noun_phrase,Verb_phrase), 
write(" Noun phrase: “,Noun_phrase),nl, 
write("Verb phrase: ",Verb_phrase),nl. 


Using append to split the List_in into possible noun phrases and 
verb phrases is not efficient, but for simple grammars it is 


adequate. 
Lf 


/* expansion of: 
sentence --> noun_phrase, verb_phrase 

Rf 

sentence(List_in,Noun_list_out,Verb_list_out) :- 
append(Noun_List_out,Verb_list_out,List_in), 


noun_phrase(Noun_list_out),!,verb_phrase(Verb_list_out). 


/* expansion of: 
noun_phrase --> determiner, noun 
noun_phrase --> noun 
ig! 
noun_phrase([A,B]) :- determiner(A),noun(B). 
noun_phrase([A]) :- moun(A). 


/* expansion of: 
verb_phrase --> verb, noun_phrase 
verb phrase --> verb, noun 
verb_phrase --> verb 
Ms § 
verb_phrase([A|B]) :- verb(A), moun_phrase(B). 
verb_phrase([A,8]) :- verb(A),noun(B). 
verb_phrase([A]) :- verb(A). 


/* the dictionary */ 
determiner("the"). 
determiner("a"). 


noun("man") . 
noun(" john"). 
noun("mary"). 
noun("dog"). 


verb("Likes"). 
verb("sees"). 
/* end of dictionary */ 


/* reader 
(1) the empty string returns the empty List, 


(2) if the string is not empty, it recursively takes the front 
token, converts it to lower case, then reads the rest of the 


list, until the string is empty. 

| 

reader("",{}) :- !. 

reader(Str, [Token|Rest]) :- 
fronttoken(Str,Tok,Str1), 
upper_lower(Tok, Token), 
reader(Stri,Rest),!. 


/* the reader */ 


/* the parser */ 


/* removes the period from list of tokens, if it exists */ 
remove_period(L1,L2) :- 

append(L2, ("."],L1). 
remove_period(L1,L1). 


append( [],List,List). 
append((H|T],L,(H|T2]) :- 
append(T,L,T2). 


LISTING 2: DIFFRENC.PRO 


/* Parsing by difference lists 
Barbara Clinger, 1988 


For input and output, this program is identical to 
Program Listing 1. However, the expansion of the grammar is 
done with difference lists rather than using append to split 
the List of tokens into noun phrases and verb phrases. 

fi 


domains 
toklist = string* 

predicates 
do 
reader(string, toklist) 
remove_perijod(toklist, toklist) 
append(toklist, toklist,toklist) 

/* The grammar */ 
sentence(toklist,toklist) 
noun_phrase(toklist, toklist) 
verb_phrase(toklist, toklist) 
determiner(toklist, toklist) 
noun(toklist, toklist) 
verb(toklist, toklist) 


/* the reader */ 


goal 
do. 
clauses 


do :- 
nl ,write("Enter a sentence --> "), 
readin(S),nl,nl, 
reader(S,List), 
write("Output of the reader: ",List),nl,nl, 
remove_period(iist,List_in), 
sentence(List_in,List_out), 


write("List out: ",List_out),nl, /* informational write */ 


List_out = [). 
/* do succeeds when List_out = [], that is, all the list was 
parsed */ 


/* sentence: 
List_in is a sentence if List_in - Y is a noun phrase and 
Y - Rest is a verb phrase. If the predicate sentence succeeds 
in parsing the entire list then Rest is the empty List. 

bd 


sentence(List_in,Rest) :- 
noun_phrase(List_in,Y),verb_phrase(Y,Rest). 


/* noun_phrase 
X is @ noun phrase 
if X - Y is a determiner and Y - Rest is a noun, 
or if X - Y is a noun. 
ied 


noun_phrase(X,Rest) :- determiner(X,Y),noun(Y,Rest). 
noun_phrase(X,Y) :- noun(X,Y). 


/* verb_phrase 
X is a verb phrase 
if X - Y is a verb and Y - Rest is a noun phrase, 
or if X - Y is a verb and Y - Rest is a noun 
or if X - Y is a verb. 
a 


verb_phrase(X,Rest) :- verb(X,Y), noun_phrase(Y,Rest). 
verb_phrase(X,Rest) :- verb(X,Y), noun(Y,Rest). 
verb_phrase(X,Rest) :- verb(X,Rest). 


/* the dictionary 


where X is ("the [Rest] , determiner is saying is that 
"the" is a determiner since ["the"] is ["the"|Rest] - Rest. 
Lf 


determiner([ "a" |Rest] ,Rest). 


determiner( ("the He ,Rest). 


noun(["man" |Rest] ,Rest). 
noun( ["john" |Rest] ,Rest). 
noun( ["mary"|Rest] ,Rest). 
noun( ["dog" |Rest] ,Rest). 


verb( ["Likes"|Rest] ,Rest). 
verb( ["sees"|Rest] ,Rest) 


/* end of dictionary */ 
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/* reader 

(1) the empty string returns the empty list, 

(2) if the string is not empty, recursively it takes the front 
token, converts it to lower case, then reads the rest of the 
list, until the string is empty. 

*/ 


reader("",[]) :- !. 

reader(Str, [Token|Rest]) :- 
fronttoken(Str,Tok,Str1), 
upper_lower(Tok, Token), 
reader(Str1,Rest),!. 


/* remove a period at the end of a sentence */ 
remove_perjod(L1,L2) :- 

append(L2, ("."],L1). 
remove_period(L1,L1). 
append( {],List,List). 
append( (H|T),L,(H]T2]) =- 

append(T,L,T2). 


LISTING 3: MATHEXP.PRO 


/* Mathematical Expression parser 


Barbara Clinger, 1988 


This program parses a mathematical expression and returns the 
value of the expression. It allows the use of ~ for exponation, 
grouping using parentheses, evaluation of functions (sine, 
cosine, ...). Decimals in the range from -1 to +1 must be entered 
with a leading zero (i.e., 0.25). A warning is issued if negative 
numbers are raised to fractional powers; the indeterminant zero 
raised to the zero power stops execution of the program. 


sample input: 2°3 + ( sin(2*pi/3) + 1 )°2 - \n(0.123) 
“y 


domains 
toklist = string* 

predicates 
reader(string, toklist) 
give_result(real,toklist, toklist) 
append(toklist, toklist, toklist) 
do 
if_can_do(real,real,real) 
is_odd_int(real) 
is_even_int(real) 

/* the grammar */ 
expr(real, toklist,toklist) 
term(real, toklist,toklist) 
power(real, toklist, toklist) 
group(real, toklist, toklist) 
number(real,toklist, toklist) 

/* goal 
do. */ 

clauses 

Go: s= 
write("When entering numbers between -1 and +1 enter"),nl, 
write("a leading zero. For example 0.15"),nl,nl, 
nl,write("Enter an expression: "),nl, write(">"), 
readin(s),nl,nl, /* get the expression */ 
reader(S,List_in), /* process for expr */ 
expr(Info_out,List_in,Rest),!, /* parse expression */ 
give_result(Info_out,List_in,Rest). /* print results */ 


give_result(N,_,T) :- 
¥ sD; 
write("The value of the expression is ", N),nl. 
give_result(_,_,T) :- 
write("Cannot evaluate the expression."),nl, 
write("Unevaluated remainder list is:"),nl,nl, 
write(T),nl,nl. 


/* THE GRAMMAR */ 
/* An expression takes the form of 
an expression plus a term, 
or an express minus a term, 
or a term 
bof 


expr(X,L1,L2) :- 
append(Left, ("+"|Right),L1), 
expr(V1,Left,L2), 
term(V2,Right,L2), 
X = V1 + V2. 
expr(X,L1,l2) :- 
append(Left, ("-"|Right],L1), 
expr(V1,Left,L2), 
term(V2,Right,L2), 
xX = V1 - v2. /* returns left value minus right value */ 
expr(X,L1,L2) :- term(X,L1,L2). 


/* returns left value plus right value */ 


/* A term takes the form of 
@ term times a power 
or a term divided by a power 
or @ power 
“/ 


term(X,L1,L2) :- 

append(Left, ["*"|Right],L1), 

term(V1,Left,L2), 

power(V2,Right,L2), 

xX = V1 * v2. /* returns left value times right value */ 
term(X,L1,L2) :- 

append(Left, ["/"|Right],L1), 

term(V1,Left,L2), 

power(V2,Right,L2), 

X= V1 / V2. /* returns left value divided by right */ 
term(X,L1,L2) :- power(X,L1,L2). 


/* A power takes the form of 
@ group raised to a power 
or a group 


Not all expressions of the form X ~ Y are possible. The clause 
if_can_do allows the obvious cases to be evaluated. 
ss f 


power(X,L1,L2) :- 

append(Left, ["""|Right],L1), 

group(V1,Left,L2), 

power(V2,Right,L2), 

if_can_do(X,V1,V2). /* check for acceptable cases */ 
power(X,L1,L2) :- group(X,L1,L2). 


/* a group takes the form of 
an expression enclosed in parentheses 
or @ number 
at f 


group(X, ("("|L1],L2) :- 

append(Sub_expr, [")"],L1), 

expr(V,Sub_expr,L2),!, 

xX =V. /* return the value inside the parentheses */ 
group(X,L1,L2) :- mumber(X,L1,L2). 


/* a number takes the form of 
a@ plus sign followed by a an unsigned number N 
or a minus sign followed by a an unsigned number N 
or sin(x), cos(x), ... , ln(x), or the number pi 
or an unsigned number N 
bat 


number (X, ("+"|T],L2)_ :- /* +N is the same as N */ 
number (X,T,L2). 
number (X, ["-"|T],L2) :- /* return negative of unsigned N */ 
number (X1,T,L2), 
X= -X1. 
number (X, ["sin"|L1],L2) :- /* use of the sine function, must */ 
group(V,L1,L2), /* be of the form sin(arg) */ 
X = sin(V),!. 
number(X, ["cos"|L1],L2) :- 
group(V,L1,L2),X = cos(V),!. 
number (X, ("tan"|L1],L2) :- 
group(V,L1,L2), X = tan(V),!. 
/* secant definition */ 
number (X, ["sec"|L1],L2) :- 
group(V,L1,L2), 
cos(V) <> 0, 
X = I/cos(V),!. 
number (_, ["sec"|L1],L2) :- 
group(V,L1,L2), 
cos(V) = 0, 
write("error in secant argument"),ni,nl,!, fail. 
number (X, ["arctan"|L1],L2) :- 
group(V,L1,L2),X = arctan(V),!. 
number (X, ("Yexp"|L1},L2) :- 
group(V,L1,L2), X = exp(V),!. 
number (X, (Un [L13,L2) :- 
group(V,L1,L2), X = In(V),!. 
number (X, ("pi"|T],T) :- 
xX = 4 * arctan(1),!. 
/* the angle whose tangent is 1 is pi/4 */ 
Number (Num, [H]T],T) :- 
str_real(H,Num),!. /* convert string to unsigned number */ 


reader("",[]) :- 1. 

reader(Str, [Tok|Rest]) :- 
fronttoken(Str,Tok,Str1), 
reader(Str1,Rest),!. 


append( [],List,List). 
append( [H|T],L,(H|T2]) :- 
append(T,L,T2). 


September/October 1988 TURBO TECHNIX 87 


/* The clause if_can_do tests some cases for the evaluation of 
expressions of the form V1 ~ V2 
bf f 
if_can_do(X,V1,V2) :- 
Vics "Oc1, /* positive base, all ok */ 
X = exp(V2 * Ln(V1)). 
if_can_do(X,V1,V2) :- /* 0 raised to 0 is indeterminant * 
v1 = 0,v2 = 0,!, 
wri te(Mttetenaaraeanes ERROR aaeaennnaneeweN) ant ; 
write("expression contains indeterminant form 0 ~ 0"),nl, 
wr i te(MAteanannnraneaNnananadRReeHAkAAeTEeeeN ) wnt ‘a nt : 
X = In(V1). /* automatic stop of program */ 
if_can_do(X,V1,_) :- 
vi = 0, /* 0 raised to nonzero power is 0 */ 
x =0. 
if_can_do(Xx, _,V2) :- 
v2 = 0, /* any number except 0 raised to */ 
Mets /* the 0 power is 1 */ 
if_can_do(X,V1,V2) :- /* negative number to an odd */ 
is_odd_int(v2), /* integer is ok */ 
X = -exp(V2 * In(abs(V1))). 
if_can_do(X,V1,V2) :- /* negative number to an even */ 
is_even_int(v2), /* integer is ok */ 
X = exp(V2 * In(abs(V1))). 
/* negative number to a fractional power can swing right or wrong. 
For example: 
(-32)° 0.2 (the fifth root of -32) is -2 
(-1024)°0.1 (the 10th root of -1024) does not exist.*/ 
if_can_do(X,V1,V2) :- 
X = exp(V2 * In(abs(V1))), 
write UERRRARRARERERERE WARNING sernaneaataenen) nt 
write("expression contains (",V1,") ~ ",V2),nl, 
write("had to use (abs(",V1,")) ~ ",V2),nl,nl. 


is_odd_int(X) .:- X = round(X), (round(X) mod 2) = 1. 
is_even_int(X) :- X = round(X). 


LISTING 4: PARSTREE.PRO 


/* Parse Tree example 
Barbara Clinger, 1988 


This program illustrates a parser for simple algebraic expressions, 
(no exponentation, parentheses, or functions). It returns the parse 
tree of the expression. The tree is built using the structure node, 
which is essentially an operator or number with left and right 
branches. 


Sample input: 2*3-4/5* 10+6 

The output is a tree which represents the number (in functor form) 
+ -€ *€2,3), *€ 04,5), 10) », 6) 

* 

/ 


domains 
item = op(string) ; leaf(real) 
mode = branch(item,node,node) ; empty 
toklist = string* 

predicates 
reader(string,toklist) 
give_result(node, toklist, toklist) 
append(toklist, toklist, toklist) 
do 

/* the grammar */ 

expr(node, toklist, toklist) 
term(node, toklist, toklist) 
number (node, toklist, toklist) 


do. 


nl,write("Enter an expression --> "), 
read(n(String),nl,nl, 
reader(String,List_in), 
expr(Tree,List_in,Rest), 
give_result(Tree,List_in,Rest). 


give_result(N, ,T) :- 
Te, 
write("The structure of the expression is:"),nl,nl, 
write N),nl. 
give_result(_,_,_) :- 
write("Cannot evaluate the expression."),nl. 


reader("™,[]) :- !. 

reader(Str, [Tok|Rest]) :- 
fronttoken(Str,Tok,Str1), 
reader(Str1,Rest),!. 
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of: 

--> expr, [+], term 
--> expr, [-], term 
--> term 


expr(branch(op("+"),L_node,R_node),L1,L2) 
append(Left, ["+"|Right],L1), 
expr(L_node,Left,L2), 
term(R_node,Right,L2). 

expr(branch(op("-"),L_node,R_node),L1,L2) = 
append(Left, ["-"|Right],L1), 
expr(L_node,Left,L2), 
term(R_node,Right,L2). 

expr(X,L1,L2) :- term(X,L1,L2). 


/* expansion of: 
term --> term, [*], number 
term --> term, [/], number 
term --> number 

fi 


term(branch(op("*"),L_node,R_node),L1,L2) 
append(Left, ["*"|Right],L1), 
term(L_node,Left,L2), 
number (R_node,Right,L2). 
term(branch(op("/"),L_node,R_node),L1,L2) : 
append(Left, ["/"|Right],L1), 
term(L_node, Left,L2), 
number (R_node,Right,L2). 
term(X,L1,L2) :- mumber(X,L1,L2). 


/* expansion of: 
number --> [+], number 
number --> [-], number 
number --> [NJ] 
ay 
number (X, ["+"|T],L2) :- 
number (X,T,L2). 
number (X, ("-"|T],L2) :- 
ene CUT EV OORYD TALE), 
= ’ 
X = branch(leaf(Z),empty, empty). 
number (branch( leaf(X),empty,empty), (H|T],T) =- 
str_real(H,X). 


append( [],List,List). 
eppend¢ (HT, L, (H[T2]) :- 
append(T,L, 2). 
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STATE SPACE 


Minimal search— maximum performance. 


Dr. Robert Crawford 


Most computer programs are reasonably 
well-behaved. In the absence of perni- 
cious bugs, a program will dutifully follow 
its algorithm, feeding on data along the 
way, then produce its results and call it a 
a wrap. Artificial intelligence programs de- 
viate from this procedural pattern, however. These 
eccentrics show not the slightest reluctance in plung- 
ing headlong into an unexplored search space in 
pursuit of an answer. All too often their nonchalant 
entry into such a system results in their program 
counter being irresistibly attracted to a black hole 
from which it never returns—and the program is lost 
in space. 

The above scenario unfolds when the program- 
mer fails to provide the program with an appropriate 
navigation system. The many techniques for guiding 
a program through its problem space are called 
search strategies. This article examines three of the 
simplest search strategies: depth-first search, 
breadth-first search, and best-first search. The depth- 
first and breadth-first searches are known as blind (or 
uninformed) methods since they utilize no heuristic 
information (or rules of thumb) about the problem. A 
best-first search, on the other hand, uses problem- 
specific information to traverse the search space 
more efficiently. Despite their differences, it turns 
out that all three approaches can be described in a 
uniform framework. We will look first at the general 
principles that are involved, and then I’ll discuss 
their implementation in Turbo Prolog. 


STATE SPACE 


One popular problem-solving technique, known as 
“state space,” is used in a wide variety of AI applica- 
tions including puzzles and games, natural language, 
and pattern-directed inference systems. This tech- 
nique uses a directed graph of nodes to represent a 
given problem. Each node in the graph, called a 
state, represents a particular problem situation. One 
node is connected to another node by an arc. An arc 
between nodes exists if it’s possible to get from the 
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first node to the second node by a legal move (some- 
times referred to as a transition). 

Now suppose that we have a directed graph that 
models a search space. One of the nodes of the 
graph, called the start node, is designated as the be- 
ginning point for the search. Also, some of the 
nodes of the graph are designated as goal nodes, and 
represent the states that we want to reach. The object 
is to find, if possible, a path from the start node to 
some goal node. A small example of such a graph is 
given in Figure 1, where node 0 is the start node and 
nodes 13, 14, and 15 are goal nodes. I'll use this 
graph as an illustration, and will presume that the 
successors of a given node are generated in increas- 
ing numerical order. 

Some preliminary bookkeeping prevents going 
around in circles, exploring a section of the graph 
over and over. I therefore assume the existence of a 
mechanism for marking the nodes of the graph. In 
addition, a couple of simple data structures are re- 
quired. The first data structure is the list L of nodes 
that have been discovered but not fully explored. 
These nodes are the possible starting points for 
further probes into the graph. The other data struc- 
ture is a collection P of pointers joining pairs of 
nodes that have been discovered. When a goal node 
is found, this collection is used to construct a path 
from the start node to the goal node. Initially, only 
the start node is marked, L contains just the start 
node, and P is empty. 

The general approach can now be described, be- 
ginning with the start node. If the start node is also 
a goal node, the search has succeeded with no effort, 
and the trivial path can be returned as the answer. If 
the start node is not a goal node, then proceed with 
the search as follows: 

1. Choose the next node; and 


a. If the list L is empty, report failure; or 


b. If the list L is not empty, remove a node N 
from L and expand the node (i.e., generate a 
list S of all of the node’s unmarked successors); 


Start Node 
(initial state) 


Goal Nodes 
(solution states) 


Figure 1. State space graph depicting node 0 as the initial state, and nodes 13, 


14, and 15 as the solution states. 
2. a. If one of these successors 
(say G) is a goal node, use P 
to generate a path from the 
start node to N, add the 
move from N to G, and re- 
turn this as the successful re- 
sult of the quest; or 


b. If no goal nodes have 

been generated, mark the 
elements of S and add them 
to L. Also add a pointer, 
which points from N to each 
element of S, to the collec- 
tion P; 

3. Go to step 1. 


All three of the search tech- 
niques that we are concerned with 
follow the outline just given. The 
difference lies in the manner with 
which the next node to be ex- 
panded is chosen. As you'll see, 
varying the way that this choice is 
made leads to strategies with 
widely disparate philosophies. 


DEPTH-FIRST SEARCHES 


Beginning at the start node, a 
depth-first search traverses down 
the levels of the search tree, 
choosing the lefthand node when- 
ever more than one node exists. 
In this way, a depth-first search 
travels down the left side of the 
search tree first. If no solution is 
found, the search backs up one 
level and tries the righthand 


node. This process continues until 
all nodes have been examined. 

In Figure 1, a depth-first search 
generates the path (0,5,8,9,14) 
from the start node 0 to the goal 
node 14. The source of the name 
“depth-first” becomes clear as the 
progress of the search is traced. 
The search moves as far down 
into the graph as it can go before 
giving up and seeking alternate 
routes. When the path (0,5,8,3,1) 
is generated during the search, a 
dead end has been reached. The 
process then backs up, first to 3 
and then to 8, before taking the 
step from 8 to 9, which eventually 
leads to success. 

In terms of our general descrip- 
tion, some care is needed when 
adding new nodes to the list L. In 
particular, always put S at the be- 
ginning of L. When the time 
comes to pick a new node for ex- 
pansion, choose the first element 
of L. In this way, the list L be- 
haves like a stack—the last ele- 
ment in is the first element out. 

The reference to “backing up” 
the search tree is reminiscent of 
the backtracking mechanism of 
Turbo Prolog—and that’s no ac- 
cident. Turbo Prolog searches for 
solutions in a depth-first fashion. 
One reason for using a depth-first 
search is that relatively little infor- 
mation needs to be maintained in 
order to recover the entire path 


once a goal node is found. The 
collection P of pointers that our 
implementation maintains is more 
than is needed for depth-first 
searching. At any stage, in fact, it’s 
only necessary to track the point- 
ers along the current path. 

Depth-first searching, however, 
is not without difficulties. A major 
problem stems from the fact that 
the graphs involved in practical 
problems are very large, and 
sometimes infinite. It’s relatively 
easy for a depth-first search to be 
led astray and to begin investigat- 
ing a hopeless path—like the 
(0,5,8,3) route in our example. If 
the graph along such an avenue 
is large or infinite, a black hole 
develops and absorbs our intrepid 
explorer. 


BREADTH-FIRST SEARCHES 


One way to avoid such a demise 
is to adopt a more cautious 
strategy for moving around in the 
graph. A breadth-first search is 
one such approach. The basic 
idea behind a breadth-first search 
is simple. Investigate the graph 
level by level, beginning with the 
root. Look next at the nodes that 
are one step removed from the 
root, then examine nodes that are 
two steps away, and so forth. In 
terms of our general paradigm, 
simply add the elements of S to 
the end of L instead of to the be- 
ginning of L, and continue to 
choose the first element of L as 
the next node to be expanded. In 
this case, the list L is used as a 
queue (a first-in-first-out list). 

When applied to the graph in 
Figure 1, the breadth-first search 
yields the path (0,6,9,14). Ata 
length of three, this is one step 
shorter than the path that is gen- 
erated by the depth-first search. 
Indeed, it’s easy to see that a 
breadth-first search always finds 
a path of minimal length between 
the start node and a goal node, 
since all paths of length n are in- 
vestigated before any paths of 
length n+1. 

You may now be wondering, “If 
a breadth-first search always yields 
the shortest possible path, why not 
use it all the time?” A primary rea- 
son is that the goal nodes may be 
quite far away from the start node. 
In such a case, a depth-first search 
may well get lucky and reach a 
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goal quickly, having explored rel- 
atively few false leads along the 
way. A breadth-first search, on the 
other hand, fans slowly down- 
ward, looking at the entire width 
of the graph until it reaches a 
goal. If all of the goals are far re- 
moved from the start node, the 
breadth-first search may take an 
intolerably long time. 

Another concern with using a 
breadth-first search is memory us- 
age. With a depth-first search, only 
the links that lead from the start 
node to the node currently being 
investigated need to be remem- 
bered in order to recapture the fi- 
nal path. A breadth-first search 
needs to remember all of the links 
in the whole bushy tree that it’s 
built in order to function, since 
the search jumps to far-removed 
sections of the tree as it progress- 
es. This exorbitant memory re- 
quirement prevents practical im- 
plementations of logic program- 
ming languages, which are based 
on a breadth-first search. 

It’s normally better to use a 
depth-first search when the search 
graph, as viewed from the per- 
spective of the start node, is long 
and deep. If the search graph is 
short and wide, breadth-first 
searching is more appropriate. 
Both methods are prone to con- 
siderable difficulties, and it’s often 
necessary to provide additional in- 
formation about the graph (over 
and above the successor relation) 
in order to obtain an effective 
technique. This is what a best-first 
search tries to do. 


BEST-FIRST SEARCHES 


In order to describe the best-first 
search, it’s necessary to make one 
additional assumption about our 
graph. Suppose that there is a rule 
by which two nodes in the graph 
can be compared in order to se- 
lect which node is more likely to 
lead to a goal node. Such a rule is 
typically based on heuristic knowl- 
edge about the particular problem 
being solved, and the rule may be 
quite inaccurate. As an example, 
take the number of each node in 
our sample graph as a measure of 
the “goodness” of the node. The 
higher the number, the more 


likely our heuristic thinks that the 
corresponding node will lead to 
success. 

The description of the best-first 
search is clear. Always expand the 
node whose heuristic value is the 
largest of all the nodes in L—in 
other words, follow your best 
guess. Whether this represents an 
improvement over the earlier 
blind methods depends entirely 
upon how good the heuristic is. 
With a typical “good but not per- 
fect” rule, a best-first search ex- 
plores the graph in a depth-first 
fashion for a while. If success is 
not forthcoming, the rule causes 
a jump to another part of the 
graph in a manner similar to the 
breadth-first search. A carefully 
chosen heuristic can often get the 
best of both worlds. In this case, 
it’s worth noting that the list L be- 
haves like a priority queue. 

A best-first search yields the 
path (0,7,10,9,14) when applied to 
Figure 1. The best-first search 
finds this path with less explora- 
tion of the graph than either the 
depth-first or breadth-first 
searches, because it only looks at 
one short deadend (involving the 
step from 10 to 4). 


IN TURBO PROLOG 


A complete implementation of all 
three search techniques is given 
in SEARCH.PRO (Listing 1). Since 
Turbo Prolog is perfectly suited to 
problems of this type, the majority 
of the code is straightforward. I'll 
touch only on the highlights here, 
paying particular attention to 
those items which need to be 
changed in order to handle differ- 
ent problems. 

The vertices of the search 
graph are represented by entries 
of type node. In Listing 1, node is 
simply a new name for integer. In 
general, the definition of the node 
domain should be modified to fit 
the problem at hand. The remain- 
ing domains—pointer, pointers, 
and path—need no adjustment 
for other problems. The graph it- 
self is described by the predicates 
start_node, goal_node, and arcc. 
Naturally, the clauses for these 
predicates must be modified to 
apply to other search spaces. 
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The predicates search and con- 
tinue_search form the heart of the 
search mechanism. The first 
clause of search says that the 
search (of whatever type) is over 
if the first node in the list of un- 
expanded nodes is a goal node. If 
this is not the case, the second 
clause of search expands the first 
(unexpanded) node and passes its 
arguments, together with the list 
of new nodes that it found, to con- 
tinue_search. In turn, continue_- 
search checks to see if a goal node 
is to be found among the newly 
generated nodes. If a new goal 
node is found, the search is over; 
otherwise, the new nodes are 
marked so that they will not be 
found again and are then merged 
into the list of unexpanded nodes. 
Finally, the pointer list is updated 
and control is passed back to 
search. 

The difference between the 
three search techniques manifests 
itself in the merge predicate. For 
the depth-first search, new nodes 
are appended to the front of the 
list of old nodes. For the breadth- 
first search, new nodes are ap- 
pended to the end of the list. In 
the case of the best-first search, an 
insertion sort inserts the new 
nodes into the list of old nodes. 
The only predicate related to 
merge that requires modification 
for other problem setups is better, 
which determines the ordering of 
nodes in the best-first search. 


NAVIGATIONAL CONTROLS 


These search methods can pro- 
vide adventurous programs with 
reliable controls. In general, blind 
searches should only be used in 
situations where no guiding infor- 
mation is available—they’re the 
hallmark of programs that are in- 
tended to be of such general ap- 
plication that no particulars can 
be assumed. The time spent in 
manufacturing an accurate navi- 
gational heuristic pays sizable div- 
idends in performance. @ 


Dr. Robert Crawford is a professor of 
computer science at Western Kentucky 
University. 


Listings may be downloaded from 


Library 1 of CompuServe forum 
BPROGB, as SEARCH.ARC. 


listing begins on page 94 


It's Easy To See Why Quattro 
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Jn fact, it's hard not to see. 
Because one look at Quattro® shows 
you a lot more for your money. 
More speed, more power, and the 
most spectacular presentation- 
quality graphics anywhere— 

built in. 


Dazzling and diverse 


If you went out looking, you'd 
be hard pressed to find spreadsheet 
graphics as dazzling and diverse 
as Quattro’s. If you did, they'd be 
in a separate standalone package 
with a separate standalone price. 
And they still wouldn't be inte- 
grated with your spreadsheet’s 
menu commands the way 
Quattro’s are. 


Brilliance built in 


Quattro lets you choose from 10 
different types of presentation- 
quality graphs and a huge selection 
of fonts, fill patterns and colors. 

Quattro supports PostScript® too. 
So you can use today’s most popu- 
lar laser printers and typesetters to 
make your work—and yourself— 
look positively brilliant. 
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Hard copy made easy 


Quattro makes it easy to get hard 
copies of your graphics—with a 
printer or plotter, directly from the 
spreadsheet. In fact, you don’t even 
have to leave the spreadsheet. 


Seeing is believing! 

Dazzling graphics are just one 
of Quattro’s eye-opening features; 
your dealer can show you the 
others. Quattro is easy to use and 
fully compatible; it even accepts 
familiar 1-2-3" compatible com- 
mands and uses data files created 
with other spreadsheets and data- 
bases. But Quattro gives you a lot 
more—in fact, twice the speed and 
power of the old standard. For only 
half the price. 


60-Day Money-back Guarantee* 


For the dealer nearest you 
call (800) 543-7543 
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66 Quattro contains the most com- 
prehensive presentation graphics 
capability available in a spread- 
sheet ... The graphs Quattro can 
produce surpass even those avail- 
able through add-on products like 
Lotus Graphwriter or Freelance 
Plus. If Borland wanted to, it could 
certainly sell the graphics portion 
of the spreadsheet on its own merit 
as a Standalone graphics application. 


Robert Alonzo, Personal Computing 


Quattro’s presentation-quality gra- 
phics output capabilities rival 

those that 1-2-3 can obtain only in 
conjunction with separate presenta- 
tion graphics software ... For me, 
at least, Quattro has certainly 
become the character-oriented 
spreadsheet program of choice. 


William Zachmann, Computerworld 


In the few years since Lotus Devel- 
opment Corp. introduced 1-2-3, 
many companies have attempted to 
unseat the king of the spreadsheet 
hill. The latest contender, Borland 
International Inc.'s Quattro, suc- 
ceeds where other spreadsheet 
packages have failed ... Quattro is 
at least two steps ahead of 1-2-3. 


Ricardo Birmele, PCResource 99 


LISTING 1: SEARCH.PRO 


/* Graph Searching */ 
domains 


node = integer /* Modify this to fit the problem. */ 


pointer = ptr(node,node) 
pointers = pointer* 
path = node* 


database 
mark (node) 


/* Predicates defining the search space */ 
/* Change these to fit the problem. Ff 


predicates 
start_node(node) 
goal_node(node) 
arcc(node, node) 


clauses 
start_node(0). 


goal _node(13). goal_node(14). goal_node(15). 


arcc(0,5). arcc(0,6). arcc(0,7). arcc(3,1). 
arcc(4,2).  arcc(5,8). arcc(6,9). arcc(7,10). 
arcc(8,3). arce(8,9). arcc(9,11). arce(9,12). 
arce(9,14). arcc(10,4). arcc(10,9). arcc(11,13). 
arcc(11,14). arcc(12,14). arcc(12,15). 


/* General purpose predicates */ 


predicates 
member (pointer, pointers) 
member (node, path) 
append(path,peth, path) 
my_retractall(string) 


clauses 
member (H, [H|_}). 
member (H,{_|T]) :- 
member (H,T). 


append( (],L,L). 
append( (H|T),L, (H|T1]) :- 
append(T,L,11). 


my_retractall(mark) :- 
retract(mark(_)), 
my_retractall(mark). 
my_retractall(_). 
/* The search mechanism */ 


predicates 


better(node,node) /* Modify this to suit the problem. 


unmarked_successor (node, node) 
search(string,path, pointers ,node, path) 

cont inue_search(string, path, pointers, node, path, path) 
insert (node, path, path) 

merge(string,peth,path, path) 

findpath(pointers,path, path) 

markal (path) 
update_pointers(node, path, pointers, pointers) 


clauses 
better(xX,Y) :- 
X >= Y. 


unmarked_successor(N,M) :- 
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ercc(W,M), 
not (mark(M)). 


search(_, (TheGoal | _],P,TheGoal,Path) :- 
goal_node(TheGoal), 
findpath(P, (TheGoal) ,Path), 
! 


search(Type, [N | R),P,TheGoal,Path) :- 
findall(X,unmarked_successor(N,X),New), 
cont inue_search(Type, [N|R],P, TheGoal ,Path, New). 


continue_search(_,(W | _],P,TheGoal,Path,New) :- 
member (TheGoal ,New), 
goal_node(TheGoal), 
findpath(P, (N, TheGoal} ,Path), 
! 


cont inue_search(Type, [N|R],P, TheGoal ,Path,Wew) :- 
markall (New), 
merge(Type,New,R,NewL), 
update_pointers(N,New,P,NewP), 
search(Type,Newl ,NewP, TheGoal , Path). 


findpath(P, [H|T],Path) :- 
member(ptr(X,H),P), 


! 
findpath(P, (X,H|T] ,Path). 
findpath(_,Path,Path). 


markall({H|T]) :- 
assert(mark(H)), 
markall(T). 

markall([)). 


insert(Node, (H|T), [(Node,H|T]) :- 
better(Node,H), 
Ie 

insert (Node, [H|T], (H|NewT]) :- 
insert(Node,T,NewT). 

insert(Node, [], [Node] ). 


merge("depth",New,R,NewL) :- 
append(New,R,NewL). 
merge("breadth" ,New,R,NewL) :- 
append(R,New,NewL). 
merge("best", [H|]T],L,NewL) :- 
insert(H,L,TempL), 
merge("best",T, Templ ,NewL). 
merge("best", (] ,Newl ,NewL). 


update_pointers(N, (H|T],P,NewP) :- 
update_pointers(N,T, [ptr(N,H) | P],NewP). 
update_pointers(_,_,NewP,NewP). 


goal 
makewindow(1,7,7,"",5,5,10,65), 
my_retractall (mark), 


write("\n\tWhat type of search (depth, breadth, best)? “), 


readin(Type), 
clearwindow, 
start_node($), 
search(Type, [S), [], TheGoal ,Path), 
write("\n\tThe goal ", TheGoal, 
"was reached via a ",Type,"-first search."), 


nl 


writec™\ta path leading from a start node to this goal is:\n\n\t", 


TAKING TO THE SCREEN 


Take control of the Turbo Prolog Toolbox for your next 


generation of screens. 


Gaylen Wood 


The Turbo Prolog Toolbox offers an array 
of screen layout tools that allow you to 
easily design input screens. One such 
tool, the screen definition tool, is a program 
that lets you interactively design a form 
on the screen. Once the screen has been 
designed, the screen definition program saves the 
Turbo Prolog description of this screen as database 
facts. This definition file can then be consulted by 
other programs. With the aid of other tools in the 
toolbox, called screen handlers, the program displays 
and uses the screens that are defined by the screen 
layout tool. This approach allows the programmer to 
design a screen visually, rather than by the trial-and- 
error methods that are usually required by program- 
ming the screen manually. 

A problem that arises is that many of the keys that 
are used by the screen handlers for input, such as 
the Tab key or the F10 key, are predefined to per- 
form in a specific manner. Other keys, including 
most of the function keys, are not defined at all. 
These tools must be modified during the develop- 
ment of a “user familiar” application so that they 
perform in a way that the end user expects. Fortu- 
nately, the source code for the screen handling tools 
is included in the Turbo Prolog Toolbox, and it’s rel- 
atively easy to modify them to suit your specific 
needs. 

In this article, I'll explain how to modify these 
tools to emulate a specific user interface. In particu- 
lar, I'll show how to enable all of the function keys, 
and how an additional key for user input can be de- 
fined. I'll also show how the Tab function can be 
given a “wrap around” capability, and we'll look at a 
method for correcting the cursor position when a 
field is full. Finally, Pll define a function to “back 
tab” from the middle of an input field. The specific 
changes that are involved in these tool modifications 
may not be of interest to everyone. The modification 
techniques, however, should interest anyxne who 
wishes to customize input screens. 


PROGRAMMER 


THE BASICS 


The process of creating a screen with the screen 
layout tool SCRDEF.PRO (which is on the distribu- 
tion disk) is fairly straightforward, and is described 
in Chapter 3 of the Turbo Prolog Toolbox User’s Guide. 
The result of this screen creation process is a consult 
file that describes text and input/output fields. This 
file is ready for consulting by the application pro- 
gram, and contains database facts that correspond to 
the following: 

field(FieldName, Type,Row,Col,Length) 
textfield(Row,Col,Length, FieldString) 
windowsize(Height,Width) 

Once the screen values have been consulted, the 
presentation of the screen and the acceptance of in- 
put are handled by the tools in SCRHND.PRO. All 
screen handling capabilities can be invoked by a sin- 
gle call to the tool serhnd: 
scrhnd(STATUSON, KEY):- 

settopline(STATUSON), 
mkheader, 
writescr, 
field(FNAME, ,R,C,_),!, 
cursor(R,C), 
chng_actfield( FNAME), 
showcursor, 
repeat, 
writescr, 
keypressed, 
readkey(KEY), 
scr(KEY), 
showcursor, 
endkey(KEY),!. 

The predicates settopline and mkheader establish 
a top line status window. The fields and associated 
screen text are then presented by writescr. The cur- 
sor is placed into the currently active field, which is 
defined by chng_actfield. Finally, showcursor dis- 
plays the cursor’s row and column position in the 
top line status window. 

Processing begins with the repeat loop, which 
presents the fields and screen text with writescr. The 
keypressed predicate keeps the program “idling” un- 
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continued from page 95 


til a key is pressed. The pressed 
key is then converted by readkey 
into a symbolic value, and the 
symbolic key’s actions are defined 
by scr. Another call to showcursor 
updates the cursor position in the 
top line status window. Next, end- 
key checks if the symbolic key is 
defined as a “quit processing” key; 
if the key is not so defined, the 
program backtracks to the repeat 
loop and begins processing again. 


DEFINING NEW KEYS 


The first changes to be made to 
the screen handling tools define 
a new key for user input and en- 
able the use of all ten function 
keys. My particular user environ- 
ment requires the + key located 
next to the numeric key pad to be 
used as an input key—after filling 
in the fields on the screen, the 
user presses the + key to tell the 
computer that input is finished. 
An additional requirement of my 
application is that the user termi- 
nate the session by using any of 
the function keys. (The original 
tool only provides the F10 key or 
the Esc key for this purpose.) Nat- 
urally, the function keys can be 
defined to perform any action you 
wish. 

To define a new key, we must 
first look at the object KEY in 
TDOMS.PRO (provided on the 
Turbo Prolog Toolbox distribution 
disk). TDOMS declares the do- 
main names for all of the keys 
that are recognized by the tools. 
To define the new key, simply pick 
an appropriate symbolic name 
and add that name to the domain 
list. (I chose the symbolic name 
plus.) Note that function keys are 
already defined by the domain 
declaration: 


fkey( INTEGER) 


There is no need to modify this 
declaration. The new version of 
TDOMS is shown in Listing 1. 
The readkey predicate, which 
reads an input character and 
returns its symbolic name, must 
now be modified to recognize the 
new key. readkey and its asso- 
ciated predicates can be found in 
TPREDS.PRO (also on the distri- 


bution disk). readkey reads a char- 


acter from the keyboard, converts 


that character into its ASCIT code 
equivalent, and passes that code 
to readkeyl. Extended keys, such 
as the function keys or Ctrl-key se- 
quences, actually generate two 
characters; the first value for an 
extended key is always 0. If read- 
keyl detects an extended key, the 
rest of the ASCII code is passed to 
readkey2, as shown in the follow- 
ing code: 
readkey1(KEY,_,0):- 

!,readchar(T), 

char_int(T,VAL), 

readkey2(KEY, VAL). 
readkey1(cr,_,13):-!. 
readkey1(esc,_,27):-!. 
readkey1(break,_,3):-!. 
readkey1(tab,_,9):-!. 
readkey1(bdel, ,8):-!. 
readkey1(ctrlbdel,_,127):-!. 
readkey1(plus,_,43):-!. 
readkey1(char(T),T,_) - 
The + key has an ASCII code of 
43, and doesn’t generate an ex- 
tended key code. Therefore, the 
+ key is included by simply add- 
ing another readkey] clause: 
readkey1(plus,_,43):-!. 
Again, fkey is already defined in 
readkey2, and there’s no need to 
modify its definition. 

The modified version of 
TPREDS.PRO is shown in List- 
ing 2. 

SCRHND.PRO defines the ac- 
tions that will be initiated by each 
of the function keys and by the + 
key. At this point, all ten function 
keys can be enabled. First, add a 
clause to ser for each additional 
key. Inspection of the clauses for 
scr reveals that a clause for 
fkey(10) is already present. There- 
fore, clauses need to be added 
only for function keys 1 through 
9, and for the + key. 


scr( fkey(1) ):-not(typeerror). 
scr( fkey(2) ):-not(typeerror). 
scr( fkey(3) ):-not(typeerror). 
scr( fkey(4) ):-not(typeerror). 
scr( fkey(5) ):-not(typeerror). 
scr( fkey(6) ):-not(typeerror). 
scr( fkey(7) ):-not(typeerror). 
scr( fkey(8) ):-not(typeerror). 
scr( fkey(9) ):-not(typeerror). 
scr( plus )  :-not(typeerror). 


not(typeerror) simply ensures that 
data in the current field is consis- 
tent with the field definition that 
was established when the screen 
was created. 

Finally, the action for each key 
is defined as follows: 
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endkey(fkey(1)):-!. 

endkey( fkey(2)):-!. 
endkey(fkey(3)):-!. 
endkey(fkey(4)):-!. 

endkey( fkey(5)):-!. 

endkey( fkey(6)):-!. 

endkey( fkey(7)):-!. 

endkey( fkey(8)):-!. 

endkey( fkey(9)):-!. 
endkey(plus):-!. 

In this case, all of these keys ter- 
minate the session. However, 
these keys can be defined to per- 
form any action you wish. 


WRAPPING THE TAB 


The Tab key is used by the screen 
handler to jump from one field to 
the next. If the Tab key is pressed 
while the cursor is located in the 
last field, however, nothing hap- 
pens. Getting the tab function to 
wrap around simply means that 
when the Tab key is pressed, the 
cursor moves from the last field 
on the screen to the first field. 
The functioning of the Tab key 
is defined in the clause scr(tab) in 
SCRHND.PRO, as shown: 


scr(tab):- 

cursor(R,C), 

nextfield(R,C). 
cursor determines the current cur- 
sor position. nextfield establishes 
the next field in the sense of left 
to right, top to bottom: 
nextfield(_,_):-typeerror,!,fail. 
nextfield(R,C):- 

field(FNAME, ,ROW,COL, ), 
gtfield(ROW,R,COL,C), 
chng_actfield(FNAME),!, 
cursor(ROW,COL). 
nextfield(_,_). 

The first clause simply verifies 
that the definitions of the fields 
are consistent, and then it fails. 
Invalid fields are skipped. The 
second clause succeeds until the 
cursor is in the last field. At that 
point, a field whose cursor values 
qualify it as the “next field” can- 
not be found, and the second 
clause fails. Turbo Prolog back- 
tracks to the next clause, which al- 
ways succeeds. As the clause is 
currently written, however, no ac- 
tion is taken—nothing happens 
on the screen. To make the Tab 
key wrap around, simply change 
the third clause to: 
nextfield(_,_):-scr(home). 


Now, when the second clause of 
nextfield fails, the third clause always 
succeeds, and the cursor is placed in 
the first defined field of the screen. 
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SideKick Plus Gives Your PC 
the Power of Communication! 


Get full communi- 
cations capabilities 
without leaving 
Quattro—or any 
other application 
youre using 

=NCI 


=NCIGET 


=MCISEND |Sends MCI Mail 
=MCISENDA|Sends MCI Mail (Advanced Service) 


: ‘ Fi Hel 
Online Help iis ———— uated 


always available 


It’s a full-fledged communi- 
cations program for data and 
voice ... plus a lot more! 


Communication is power. And with 
SideKick® Plus, it’s at your fingertips. 
Because SideKick Plus is the only com- 
munication software you need. To send 
your message around the world. Or to 
pick up messages from MCI or Dow 
Jones or any other electronic service. 
Automatically—even if you’re down 
the hall in a meeting. Or doing some- 
thing else you do on your PC. (Try 
asking CrossTalk® software to do that!) 

SideKick Plus saves you time and 
keystrokes with sample scripts for pop- 
ular programs like MCI® Mail, Compu- 
Serve,® and BIX.® You can create 
scripts by simply recording your key- 
strokes, or edit scripts to access the 
full power of the script language. 


Turbo charge your Phonebook 


SideKick Plus lets you create the 
most high tech address books you've 
ever seen—entering names and 
addresses in the form you choose. 
Searching electronically for the infor- 
mation you need. And attaching notes 
and comments about each person 
listed. 


Logon to MCI (Both Services) 
=MCIBOTH |Gets and Sends MCI Mail 
=MCIBOTHA|Gets and Sends MCI Mail (Advanced) 
Gets MCI Mail 


Phonebook Script 


@mc inane ,cr 
"word: ",26 
@mcipsu,cr 


write 
match 
write 


match "MCI" ,68 

select (68) 

case "Your INBOX has” 
match “command” ,38 


Put 
Put 
Put 
Put 


Put 
Put 


Zoom 
Switch 


Begin Blk 


Print End Blk 


number here 
number here 


Ready-to-use scripts 
make it easy to log 
onto MCI, Compu- 

Serve, or BIX 


> reply with Glos 
; Wait for pass 
> reply with Glos 


> Waits Tor-4CL_ 
; Check for messa 
> Someone likes m 
> Wait for prompt 


Define your pass- 
word and encrypt it 
for security 


number here 
number here 
number here 
number here 


Add in your local 
access number with 
a simple entry 


Menu 


-Syntax Check and Exit 


SideKick Plus is communications 
and more: seven powerful 
software packages in one! 


= A complete outliner that lets you 
open nine files at once 

= A sophisticated DOS file manager 

= A calendar you can use as a common 
scheduler if you're on a local area 
network 

= Multiple notepads 

= A phonebook with full communications 

= Your choice of four different calculators 

= An ASCII table 


Plus: 


= Support for both expanded and extended 
memory. If you have an Intel Above® 
Board, you can take full advantage of 
your 640K of RAM and yet use all 
your SideKick Plus desk accessories 
at any time. 

= All completely integrated and instantly 
accessible over any other application 
you're working in 

= A|l taking up as little as 72K of your 
computer's RAM 


Minimum System Requirements; For IBM PS/2, IBM family of personal com- 
puters, and all 100% compatibles. Operating system: PC -DOS (MS-DOS) 2.0 
or later. Minimum system memory: 384K bytes. Minimum resident memory 
size: 72K. Hard disk required. Supports both EMS and extended memory 


*Customer satisfaction is our main concern; if within 60 days of purchase this 
product does not perform in accordance with our claims, call our customer 
service department, and we will arrange a refund 


All Borland products are trademarks or registered trademarks of Borland International, Inc. Other 
brand and product names are wademarks of their respective holders. 


Copyright ©1988 Borland International. Inc BI 12384 


66 The built-in communications 
program is very impressive ... 
Unlike most communications pro- 
grams (including some that cost 
twice as much as SideKick), the 
new SideKick lets your computer 
communicate with another machine 
while you are running another 
program. 

—Lawrence Magid, Washington Post ‘y by 


Get the power! 


To buy this kind of communication 
power and all the other SideKick Plus 
features separately, you'd spend 
hundreds of dollars and drain your 
computer's memory dry. Instead, just 
see your Borland dealer and get the 
power of SideKick Plus! 


Hard disk required. 


60-Day Money-back Guarantee* 


For the dealer nearest you 
Call (800) 543-7543 


TAKING TO THE SCREEN 


continued from page 96 


AUTO FILL WITH 
WRAPAROUND 


Perhaps the most significant en- 
hancement in terms of appear- 
ance is the modification of the ac- 
tions that occur when a field has 
been filled. The goal is to have 
the cursor move to the next field. 

As each character is entered, it’s 
processed by ser(char(T)) in 
SCRHND.PRO. ser(right), which 
is the last call in ser(char(T)), han- 
dles the cursor as each character 
is entered. This process is shown 
in the following code: 
ser(right):- 

actfield( FNAME), 

not(noinput(FNAME)), 

field(FNAME, , _,C,L), 

cursor(ROW,COL), 

COL<C+L-1,!, 

COL1=COL+1, 

cursor(ROW,COL1). 
scr(right):-move_right. 
If the current field is not full, the 
first clause of ser(right) moves the 
cursor to the right. If the current 
field is full, then the second 
clause goes into action. 

The temptation is to resolve the 
algorithm in move_right. Thanks 
to the declarative nature of Turbo 
Prolog, there’s an easier way— 
simply tell the second clause of 
scr(right) to act like the Tab key. 
The second clause then becomes: 


ser(right):-scr(tab). 


This method resolves more 
than the auto fill issue. Because 
the Tab key was previously mod- 
ified to wrap around, the auto fill 
wraps also. When the last field is 
full, the cursor returns to the first 
field on the screen. 


BACK TAB FROM THE 
MIDDLE OF A FIELD 


Another useful feature is the abil- 
ity to back tab (Shift-Tab) from the 
middle of a field and move the 
cursor to the start of the field. 
The clause ser(btab) in 
SCRHND.PRO defines the back 
tab function. ser(btab) establishes 
the current cursor position and 
calls prevfield. prevfield only suc- 
ceeds when the cursor is in the 
first position of any field other 
than the first field. prevfield, 
along with chk_found, uses a fail 
to encourage Turbo Prolog’s back- 


tracking mechanism to do the 
work. The following code demon- 
strates this process: 
prevfield(_,_):-typeerror,!,fail. 
prevfield(R,C):- 
field(FNAME, ,ROW,COL, ), 
chk_found( FNAME ,R,C,ROW,COL),!, 
actfield(F1), 
field(F1,_,RR,CC,_),!, 
cursor(RR,CC). 


chk_found(_,R,C,R,C):-!. 
chk_found( FNAME, ag hry gE ): 2 

chng_ actfield(FNAME), fail. 

Let’s create a hypothetical ex- 
ample to see how this works. 
Assume that the cursor is located 
in the first character position of 
the third field on a screen when 
the back tab function is invoked. 
When prevfield is called, field re- 
trieves the values for field1 on the 
screen from the internal database. 
Those values are then passed to 
chk_found, along with the cursor 
position of the currently active 
field. The first clause of chk_- 
found fails, since the row and col- 
umn values of the current field 
are not equal to the row and col- 
umn values for fieldl. The second 
clause establishes field1 as the 
previous field, and then fails. 

prevfield repeats the process, 
retrieving the values for field2 on 
the screen. Once again, chk_- 
found checks if the row and col- 
umn values correspond to the cur- 
rently active field. The first chk_- 
found clause fails, the second 
clause establishes field2 as the 
previous field, and the program 
backtracks once again. On the 
third pass, chk_found verifies that 
the cursor values of field3 corre- 
spond to the currently active field. 
The remaining subgoals of prev- 
field determine the corresponding 
row and column values for this 
field, and place the cursor appro- 
priately. 

chk_found must determine if 
the current cursor position is 
within a defined field, and if so, 
reestablish the current field as the 
active field. First, the predicate 
declaration of chk_found must be 
expanded as follows, in order to 
include the length that corre- 
sponds to the row and column 
values being used: 


chk_found( FNAME , ROW, COL, ROW, COL, LEN) 
Next, prevfield must be modified 


to include the new parameter in 
the call to chk_found. The final 
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step is to modify the existing chk_- 
found clauses and add a new 
chk_found clause. Since the exist- 
ing two clauses of chk_found don’t 
require the new parameter, this 
parameter may be included as an 
anonymous variable. The new 
chk_found clause, however, does 
use that new variable, as the fol- 
lowing code demonstrates: 
chk_found(_,R,C,R,C,_):-!. 
chk_found(FNAME,R,C,R,COL,LEN):- 

C > COL, 

C < COL + LEN, 

chng_actfield( FNAME). 


Is 
chng_ actfield(FNAME), fail. 


The second clause of chk_- 
found now checks if the current 
cursor position, which is provided 
by prevfield, is located in a de- 
fined field. If the current cursor 
position is in a defined field, then 
chk_found establishes that field as 
the currently active field, and al- 
lows chk_found to succeed. 

Now, when the cursor is located 
in the middle of a field and the 
back tab function is used, the cur- 
sor returns to the first character 
position of that field. If used fur- 
ther, the back tab function will act 
as originally defined. 

If you’re using Turbo Prolog 2.0, 
you must make one other change. 
SCRHND defines a predicate 
called trunc to truncate strings. In 
Turbo Prolog 2.0, trunc is a built- 
in predicate that truncates a real 
number and returns its integer 
value. Therefore, you need to 
change the name of the toolbox 
predicate from trunc to something 
else, such as trunc_. 

Listing 3 incorporates all of 
the changes that were made to 
SCRHND.PRO. The file TEST- 
PROG.PRO (Listing 4) contains a 
short program that tests the 
changes. (HNDBASIS.PRO from 
the distribution disk was used as 
a template for creating this test 
program.) Run these programs 
and observe the changes. I’m sure 
you'll find that your own personal 
requirements can also be easily 
incorporated into the already 
powerful Turbo Prolog Toolbox. 


Gaylen Wood is a senior systems ana- 
lyst for the packaging division of the 
Weyerhauser Paper Company. 


Listings may be downloaded from 
Library 1 of CompuServe forum 
BPROGB, as SCRHND.ARC. 


LISTING 1: XTDOMS.PRO 


/* Listing 1: XTDOMS.PRO “y/ 


[IIR III ISI ITA III IIA IAI IIA IO A IOS IIIS ISIS ISAISA IASI AAA 


Turbo Prolog Toolbox 
(C) Copyright 1987 Borland International. 


In order to use the tools, the following domain declarations 
should be included in the start of your program 


RRA R RRA ARRRE RRR ERR REE RAR RER EEE EERE EREER ERA ERREREEREREER J 
[IRI IIR RII IRI IIIA III IAI IAI IAAI IAI IASI ASIA SAAS IDE 


* Modified 2/5/88 G. Wood 
* added 'plus' to domain of KEY. See changes in 
* = XTPREDS.PRO and XSCRHND.PRO 


RRR RRRARRR RE RR RAR RARER ERE RERE ERE EERE REE RE RE ERERRERERERE / 


DOMAINS 

ROW, COL, LEN, ATTR = INTEGER 

STRINGLIST = STRING* 

INTEGERLIST = INTEGER* 

KEY = cr; esc; break; tab; btab; del; bdel; ctribdel; ins; 
end ; home ; fkey(INTEGER) ; up ; down ; left ; right ; 
ctrlleft; ctriright; ctrlend; ctrlhome; pgup; pgdn; 
ctrlpgup; ctripgdn; char(CHAR) ; plus; otherspec 


LISTING 2: XTPREDS.PRO 


/* Listing 2: XTPREDS.PRO bad é 


Y halaichahahaiehaiatelalaleialaieiaiahaieieleiaisisiaiaiaialalaiaisisisislalciaishchsieisialeislelaisialeleisichaieheiaisiaialalel 


Turbo Prolog Toolbox 
(C) Copyright 1987 Borland International. 


This module includes some routines which are used in nearly 


all menu and screen tools. 
ARHARERRARARARRRRRERERRRERRRERRRRRRERERREERAERRRRERARERRRERERRE EE 7 


RAI III III III II TIT I IO AI III IAAI IAAI AAI IAI SAS ISA SISA IAA 


* Modified 2/5/88 G. Wood 
* Added the '+' key (as 'plus') to be a recognized key 
* See predicate readkey1 (below) and changes in XTDOMS.PRO 


a and XSCRHND .PRO 
FEI III III III IIR III RIT IIR III III IIIA IA IIIS ISA IA SASS 


[RRRRRRRERR AAAI RIERA REAR ERE REREEREEER EERE EEREREEREREREERE 7 


is repeat */ 
[ARRRRERARRARRAARRRRERRRERERARERREERREREREERERRERAERRERARRRAERREE / 


PREDICATES 
nondeterm repeat 


CLAUSES 
repeat. 
repeat: -repeat. 


RARITIES IRI IIT IITA I ISO RI IIIA IA IAIII 


Fie! miscellaneous Ws 
[RRRARERAARAARARRARRREARERERERRERERERERRERERREERRERERAEREREEREERE / 


PREDICATES 

max len(STRINGLIST,COL,COL) 

/* The length of the longest string */ 
Listlen(STRINGLIST,ROW) 

/* The length of a list ad f 
writelist(ROW,COL,STRINGLIST) 

/* used in the menu predicates bal 
reverseattr(ATTR,ATTR) 

/* Returns the reversed attribute */ 
min(ROW, ROW, ROW) 
min(COL,COL,COL) 
min(LEN,LEN,LEN) 
minC INTEGER, INTEGER, INTEGER) 
max (ROW, ROW,ROW) max(COL,COL, COL) 
max(LEN,LEN,LEN) max( INTEGER, INTEGER, INTEGER) 


CLAUSES 
max en( [H|T] ,MAX,MAX1) =~ 
str_len(H, LENGTH), 
LENGTH>MAX,!, 
maxlen(T,LENGTH,MAX1). 
maxlen( (_|T] ,MAX,MAX1) :- maxlen(T,MAX,MAX1). 
maxlen( (], LENGTH, LENGTH). 


listlen((],0). 

listlen( (_|T],N):- 
Listlen(T,x), 
N=X+1. 


writelist(_, ,()). 

writelist(LI,ANTKOL, (H|T]):- 
field_str(LI,0,ANTKOL,H), 
LI1=LI+1, 
writelist(L11,ANTKOL,T). 


min(X,Y,X):-X<=Y,!. 
min(_,X,X). 


man(X,Y,X):-X>=Y,!. 
max(_,X,X). 


reverseattr(A1,A2):- 
bitand(A1,$07,H11), 
bitleft(H11,4,H12), 
bitand(A1,$70,H21), 
bitright(H21,4,H22), 
bitand(A1,$08,H31), 
A2=H12+H22+H31. 


Y Aahaiahaiaiaiahahahahahaheleiebalsieiaicicialaheleislehelalahaieieiaiaielaiielsiaialshahaieiaiaieleiaielsiaiaialaisinisistalaiad A 


Pied Find letter selection in a list of strings 
1S Look initially for first uppercase letter. 


ve! Then try with first letter of each string. 
[PARAAAARAAEEREERERRRERERAEEREEEREEREERERORAENO NR RHERREREREEEEEEE / 


PREDICATES 
upe(CHAR,CHAR) lowc(CHAR, CHAR) 
try_upper (CHAR, STRING) 
tryfirstupper(CHAR,STRINGLIST,ROW, ROW) 
tryfirstletter(CHAR,STRINGLIST,ROW, ROW) 
tryletter(CHAR,STRINGLIST,ROW) 


CLAUSES 
upe (CHAR, CH):- 
CHAR>='a' ,CHAR<='z',!, 
char_int(CHAR,C1), C11=C1-32, char_int(CH,CI1). 
upe(CH,CH). 


lowc (CHAR ,CH):- 

CHAR>="A' ,CHAR<='2',!, 

char_int(CHAR,CI), C11=C1+32, char_int(CH,CI1). 
lLowe(CH,CH). 


try_upper (CHAR, STRING): - 
frontchar(STRING,CH,_), 
CH>='A' ,CH<='2Z', 1, 
CH=CHAR. 

try_upper (CHAR, STRING): - 
frontchar(STRING, ,REST), 
try_upper(CHAR,REST). 


tryfirstupper(CHAR, [W|_],N,N) :- 
try_upper(CHAR,W),!. 

tryfirstupper(CHAR, [_|T],N1,N2) :- 
W3 = N1+1, 
tryfirstupper(CHAR,T,N3,N2). 


tryfirstletter(CHAR, [W|_],N,N) :- 
frontchar(W,CHAR,_),!. 

tryfirstletter(CHAR, [_|T],N1,N2) :- 
N3 = N1+1, 
tryfirstletter(CHAR,T,N3,N2). 


tryletter(CHAR, LIST, SELECTION): - 

upe (CHAR, CH), tryfirstupper(CH,LIST,O,SELECTION),!. 
tryletter(CHAR, LIST, SELECTION) :- 

Lowc(CHAR,CH), tryfirstletter(CH,LIST,0,SELECTION). 


[RRRRRRRRRRRRARE RARER ERERERREREREEEREREERERERERREREREREREER ARERR / 


/* adjustwindow takes a windowstart and a windowsize and adjusts */ 
/* the windowstart so the window can be placed on the screen. sl dh 
/* adjframe looks at the frameattribute: if it is different from */ 
/* zero, two is added to the size of the window */ 


[RRRRRARRRERRRRERARERERER RARE ER EER ERERERERERERERERER ER ERE R EERE 7 


PREDICATES 


adjustwindow(ROwW, COL, ROW, COL ,ROW, COL) 
adj frame(ATTR ,ROW, COL, ROW, COL) 


CLAUSES 
adjustwindow(L1,KOL,DLI ,DKOL,ALI,AKOL):- 
L1<25-DLI,KOL<80-DKOL,!,ALI=LI,AKOL=KOL. 
adjustwindow(LI,_,DL1,DKOL,ALI ,AKOL):- 
L1<25-DLI,!,ALI=L1,AKOL=80-DKOL. 
adjustwindow(_,KOL,DL1,DKOL,ALI ,AKOL):- 
KOL<80-DKOL,!,AL1=25-DLI, AKOL=KOL. 
adjustwindow(_,_,DL1,DKOL,ALI,AKOL):- 
ALI=25-DLI, AKOL=80-DKOL. 
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adjframe(0,R,C,R,C):-!. 
adjframe(_,R1,C1,R2,C2):-R2=R1+2, C2=C1+2. 


[RAI IIR IAI IAAI AIR AIA IA AIA II IIIA ASIII IIIA SSSA AI IIIA, 


i Readkey 
/* Returns a symbolic key from the KEY domain 


[PERERA IAAI IARI RRA ERE ERIE II SII IIIS III SII IS. | 
Y hnlaiahaiaiaiahaiaiahaialelaieieisiahsiahainiaiaieiheiaiaiehaheiehaielehsiaiaieleleleieisielelaleisieieiciaiaicisisinisisisiaiel A 


/* Modified 2/5/88 G.Wood <7 
/* Added readkey1 clause for symbolic key 'plus' with ASCII 43*/ 


[IIIA IRR IR IRIE IRR III II III IISA I III ISIS I IIS II IIA 


PREDICATES 
readkey(KEY) 
readkey1(KEY,CHAR, INTEGER) 
readkey2(KEY, INTEGER) 


CLAUSES 
readkey(KEY):-readchar(T),char_int(T, VAL), readkey1(KEY,T,VAL). 


readkey1(KEY,_,0):-!,readchar(T),char_int(T, VAL), readkey2(KEY,VAL). 


readkeyl(cr,_,13):-!. 
readkeyl(esc, _,27):-!. 
readkey1(break, ,3):-!. 
readkey1(tab,_,9):-!. 
readkey1(bdel,_,8):-!. 
readkeyl(ctrlbdel, ,127):-!. 
readkey1(plus, ,43):-!. 
readkey1(char(T),T,_) - 


readkey2(btab,15):-!. 
readkey2(del ,83):-!. 
readkey2(ins,82):-!. 
readkey2(up,72):-!. 
readkey2(down,80):-!. 
readkey2(left,75):-!. 
readkey2(right,77):-!. 
readkey2(pgup, 73):-!. 
readkey2(pgdn,81):-!. 
readkey2(end,79):-!. 
readkey2(home,71):-!. 


readkey2(ctrileft,115):-!. 

readkey2(ctriright,116):-!. 

readkey2(ctrlend,117):-!. 

readkey2(ctrlpgdn,118):-!. 

readkey2(ctrlhome,119):-!. 

readkey2(ctrlpgup, 132):-!. 

readkey2(fkey(N),VAL):- VAL>58, VAL<70, N=VAL-58, !. 
readkey2(fkey(N),VAL):- VAL>=84, VAL<104, N=11+VAL-84, !. 
readkey2(otherspec,_). 


LISTING 3: XSCRHND.PRO 


/* Listing 3: XSCRHND.PRO */ 


[RRRRRAAAA AAA RARER ARERR EER EARER ARERR ERE EERE ERE RR EERE 


Turbo Prolog Toolbox 
(C) Copyright 1987 Borland International. 


SCRHND 


ses=== 
This module implements a screen handler called by: 


scrhnd( TOPLINE , ENDKEY) 


TOPLINE = on/off - determines if there should be a top line 


ENDKEY - Esc or F10 used to return values 
REAR RRRERRERARARERAARRRER EERE EERERREREERERRERREREERERRERER EE / 


Y hehahaiaiaialalahaleiaialahaieiahaiaiaieieteiaialataiaieleialaiaiaiaiaielaisiehalcialalehsisisieisislelalisinieisicislsiciaiel 


* Modified 2/5/88 G.Wood 
Added capabilities to: 


- allow the tab to wrap-around 
- correct cursor positioning when an input field is filled, 
including wrap-around 


See clauses scr 
nextfield 
chk_found 


prevfield 
SERA ERREERERERRRERRERERERERERERREREERREREREREEEREREREERE 7 


ese eee ee eee 


100 TURBO TECHNIX September/October 1988 


- enable all function keys and define an additional input key 


- define a back tab function from the middle of an input field 


/* 
DOMAINS 
FNAME=SYMBOL 
TYPE = int(); str(); real() 


DATABASE 
/* Database declarations used in scrhnd */ 
insmode /* Global insertmode */ 
actfield( FNAME) /* Actual field */ 
screen(SYMBOL ,DBASEDOM) /* Saving different screens */ 
value( FNAME, STRING) /* value of a field */ 
field( FNAME, TYPE,ROW,COL,LEN) /* Screen definition */ 
txtfield(ROW,COL,LEN, STRING) 
windows ize(ROW, COL). 
notopl ine 


/* DATABASE PREDICATES USED BY VSCRHND */ 
windowstart (ROW, COL) 
mycursord(ROW, COL) 


/* Database declarations used in lineinp */ 
Lineinpstate(STRING,COL) 
my 


PREDICATES 
/* SCREEN DRIVER */ 
scrhnd( SYMBOL , KEY) 
endkey (KEY) 
scr(KEY) 
writescr 
showcursor 
mkheader 
showoverwrite 


ass_val (FNAME, STRING) 
val id( FNAME, TYPE, STRING) 
typeerror 


chng_actfield( FNAME) 
field_action( FNAME) 
field_value( FNAME, STRING) 
noinput (FNAME ) 


types (INTEGER, TYPE,STRING) /* Definition of the known types */ 


[PARRRRRRAR ARERR RRERER REE ERERER EERE EREREREERERE REE ER EERE EERE IRE 7 


Va Create the window 
/* This can be used to create the window automatically from the 


/* windowsize predicate. 
[PARRRARARAARERARRERRARERAERREARREERREERERAERARREREREERERRRREERRE ED 7 


PREDICATES 
createwindow(SYMBOL ) 


CLAUSES 

createwindow(off):- 
windowsize(R,C),!, 
R1=R+3, C1=C+3, 
makewindow(81,23,66,"",0,0,R1,C1). 

createwindow(on):- 
windowsize(R,C),!, 
R1=R+3, C1=C+3, 
makewindow(85,112,0 
makewindow(81,23,66," 


Y haichaiahahaiehabalahalelalalahehalalatalalaiatalaleleiaiaialeieleislelchahalelehehshahshsheleheleieeiaiaieiaicisisheleieiaislelel A 


/* Intermediate predicates i A 


T hniahehaiahahalalalchtalelalahelaiaiehahslahehaiatehehiatalalelalshaletetehaleielelaieieielalelelelelehclclaleisiaiaielelelalalel | 


PREDICATES 
trunc_(LEN, STRING, STRING) 
oldstr( FNAME, STRING) 
settopl ine(SYMBOL) 


CLAUSES 
endkey( fkey(10)):-!. 
endkey(esc). 
[PRERERARERAERERRARRERERERERREREEAERRRERER AREER REREERERRRRER 
* Modified 2/5/88 G.Wood 
Added clauses to endkey for fkeys 1 thru 9, and 
new symbolic key 'plus.' Allows these keys to terminate 
the screen handling predicate, scrhnd 
SRARAERARERERREAEREERERERRARRAR ERE ARRAEREREEERERRERERERERERRE / 
endkey( fkey(1)):-!. 
endkey(fkey(2)):-!. 
endkey( fkey(3)):-!. 
endkey(fkey(4)):-!. 
endkey(fkey(5)):-!. 
endkey( fkey(6)):-!. 
endkey(fkey(7)):-!. 
endkey( fkey(8)):-!. 
endkey( fkey(9)):-!. 
endkey(plus):-!. 


trunc_(LEN,STR1,STR2):-str_len(STR1,L1),L1>LEN,!, 

frontstr(LEN,STR1,STR2,_). 
trunc_(_,STR,STR). 
settopline(_):-retract(notopline), fail. 
settopline(off):-!,assert(notopline). 
settopline(_). 


oldstr( FNAME ,S):- value(FNAME,S),!. 
oldstr¢_,""), 


ass_val(FNAME, ):- retract(value(FNAME, )), fail. 
@ss_val (FNAME, VAL):-VAL><"", assert(value( FNAME ,VAL)), fail. 
ass_val(_,_). 


chng_actfield(_):-typeerror,!, fail. 

chng_actfield(_):- 
retract(actfield(_)), fail. 

chng_actfield( FNAME) :- 
assert(actfield(FNAME)). 


typeerror:- 
actfield( FNAME), 
field(FNAME, TYPE, , ,_), 
value( FNAME, VAL), 
not(valid( FNAME, TYPE,VAL)), 
beep,!. 


valid(_,str,_). 
valid(_,int,STR):-str_int(STR,_). 
valid(_,real,STR):-str_real(STR,_). 


/* The known types */ 
types(1,int,"integer"). 
types(2,real,"real"). 
types(3,str,"string"). 


[ARERR ARRA RARE RARE RE REAR RRERERRRR ARERR REREREREREERERER AREER RE 7 


fas SCREEN DRIVER */ 
/* Screen definition/input is repeated until F10 is pressed tf 


Y hahahahaiahahahahahsiaiaiaheiaiahaiaiaiaisheiahalaialahahaiehaleielshalelsiaiciaielslaiahsleiaiaheieisisisieisiaisinielicielcieiaiel | 


scrhnd(STATUSON, KEY) :- 

settopl ine(STATUSON), 

mkheader, 

writescr, 

field( FNAME, ,R,C,_),!,cursor(R,C), 

chng_actfield( FNAME), 

showcursor, 

repeat, 

writescr, 

keypressed,/*Continuation until keypress means 
that time dependent 
user functions can be updated*/ 

readkey(KEY), 

scr(KEY), 

showcursor, 

endkey(KEY),!. 


[PPRARARRARAERAARRRARRERARARRRAERREEERERAREAREREREREEREEREEREREERE / 
oe Find the next field 7] 


[PRRRRRRARARAERERRERER ERE ERRER REAR EEEREEEREREREREERAEAREREER ERE / 


PREDICATES 
/* The predicates should be called with: 

ACTROW, ACTCOL, MAXROW, MAXCOL, NEWROW, NEWCOL */ 
best_right (ROW, COL ,ROW,COL,ROW, COL) 
best_left (ROW, COL ,ROW, COL, ROW, COL) 
best_down(ROW, COL, ROW, COL ,LEN,ROW, COL) 
best_up(ROW,COL , ROW, COL,LEN,ROW,COL) 
better_right(ROW,COL,ROW,COL,ROW,COL) 
better_Lleft(ROW, COL ,ROW, COL ,ROwW,COL) 
better_field(ROW,COL ,ROW,COL,LEN,ROW,COL,LEN) 
calcdist(ROW,COL,ROW,COL,LEN,LEN) 
move_left 
move_right 
next field(ROW,COL) 
gtfield(ROW, ROW, COL,COL) 
prevfield(ROW, COL) 

[PARRRRRARERARRRRARERERERERERRERREREREREERERERER ER EEE 

* Modified 2/5/88 G.Wood 

* Added LEN to predicate chk_found. See changes to 

* —chk_found clause. 


SRARAAAEAAAEREREREREERAEREREAEREEREREREEERERRERRERE 7 
/* chk_found( FNAME ,ROW,COL,ROW,COL) */ 
chk_found( FNAME , ROW, COL ,ROW, COL, LEN) 
setlastfield 


CLAUSES 


best_right(RO,CO,R1,C1,ROW,COL):- 
field(_, _,R2,C2,_), C2>CcO, 
better_right(RO,CO,R1,C1,R2,C2),!, 
best_right(R0,CO,R2,C2,ROW,COL). 

best_right(_,_,R,C,R,C). 


better_right(RO,_,R1,_,R2,_):-abs(R2-RO)<abs(R1-RO),!. 
better_right(RO, ,R1,C1,R2,C2):-abs(R2-RO)=abs(R1-RO),C2<C1. 


best_left(RO,CO,R1,C1,ROW,COL):- 
field(_,_,R2,C2,_), C2<CO, 
better_left(RO,CO,R1,C1,R2,C2),!, 
best_left(RO,CO,R2,C2,ROW,COL). 

best_left¢_,_,R,C,R,C). 


better_left(RO,_,R1,_,R2,_):-abs(R2-RO)<abs(R1-RO),!. 
better_left(RO, ,R1,C1,R2,C2):-abs(R2-RO)=abs(R1-RO),C2>C1. 


best_down(RO,CO,R1,C1,L1,ROW,COL):- 
field(_,_,R2,C2,L2), R2>RO, 
better_field(RO,CO,R1,C1,L1,R2,C2,L2),!, 
best_down(RO,CO,R2,C2,L2,ROW,COL). 

best_down(_,_,R,C,_,R,C)- 


best_up(RO,CO,R1,C1,L1,ROW, COL) :- 
field(_,_,R2,C2,L2), R2<RO, 

,  better_field(RO,CO,R1,C1,L1,R2,C2,L2),!, 
best_up(RO,CO,R2,C2,L2,ROW,COL). 

best_up(_,_,R,C,_,R,C). 


better_field(RO,CO,R1,C1,L1,R2,C2,L2):- 
calcdist(RO,CO,R1,C1,L1,DIST1), 
calcdist(RO,CO,R2,C2,L2,DIST2), 
DIST2<DIST1. 


calcdist(RO,CO,R1,C1,L1,DIST):- 
C11=C1+L1, 
max(C0,C1,H1), 
min(H1,C11,H2), 
DIST=3*abs(R1-RO)+abs(H2-CO). 


move_left:- 
not(typeerror), 
actfield(FNAME), 
field(FNAME, ,R,C,_),!, 
best_left(R,C,-100,-100,ROW,COL), 
field(F1, ,ROW,COL, _), 
chng_actfield(F1),!, 
cursor(ROW,COL). 


move_right:- 
not(typeerror), 
actfield( FNAME), 
field(FNAME, ,R,C,_),!, 
best_right(R,C,-100,-100,ROW,COL), 
field(F1, ,ROW,COL,_), 
chng_actfield(F1),!, 
cursor (ROW,COL). 


[OCI III IR IIT III TOI IITA TA IAA IAAI IIA IIA III ISI IN 


* Modified 2/5/88 G. Wood 
Changed chk_found clause in prevfield to include LEN. 
Changed existing chk_found clauses to incorporate the 
additional variable position. 
Added new chk_found clause (second position) to check 
if current cursor position is in a defined field 
These changes will allow use of back-tab when anywhere 


in a field to return to first character of field then 


proceed to “back up" one field at a time. 


SRRRERERERRERERERREREERRARER EERE EEREREREEEREEREREREAERERERED / 


prevfield(_,_):-typeerror,!,fail. 
prevfield(R,C):- 
field( FNAME, ,ROW,COL,LEN), 
chk_found( FNAME ,R,C,ROW,COL,LEN),!, 
actfield(F1), 
field(F1,_,RR,CC, ),!, 
cursor(RR,CC). 


sof. 
R,COL,LEN):~ 


chk_found(_,R,C,R,C,_) 
c, 


chk_found( FNAME ,R, 
C > col, 
C < COL + LEN, 
chng_actfield( FNAME). 
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Y hataiatahalahahalaiahalalaialahalehalelaieialhelalelelahshabalehsiehstaialabaleielaiaheisiaialaiebaisiaisiaialebslsiaisiailalalal 


* Modified 2/5/88 - G.Wood 
Commented out nextfield(_,_) and replaced with indicated clause. 
This will allow the scr(tab) clause to "wrap around" from last 
field to first field, and changes to scr(right) to allow filling 
last field and "wrap around" to first field. 


RRARARARERER REAR RRR EERE KI TIER ERR ERE EEE ERE REED 7 


scr( fkey(5) ):-not(typeerror). 
scr( fkey(6) ):-not(typeerror). 
scr( fkey(7) ):-not(typeerror). 
scr( fkey(8) ):-not(typeerror). 
scr( fkey(9) ):-not(typeerror). 
scr¢ plus ) :-not(typeerror). 


ser(right):- 
actfield(FNAME), 
Not (noinput(FNAME)), 
field(FNAME, ,_,C,L), 
cursor(ROW,COL), COL<C+L-1,!, 
COL1=COL+1, 
cursor(ROW,COL1). 
[III III ITT TAIT IITA IAI AAAI I III AAI AI IAI SAI I AI IAI AT 
* Modified 2/5/88 - G.Wood 
* Commented out scr(right):-move_right and replaced with 
indicated clause to allow an auto-skip from active 
field when full to next field, next im the sense of left to 
right, top to bottom. 
See changes to nextfield clause which will cause "wrap around” 
to first field when last field is filled 


ss hadadadadiahalehelchahahelehebehalehelahahehehelelehahalelelehehehehehchehcleioiohaiahalelalcielaleieieieieleieieieieieleieielel | 


nextfield(_,_):-typeerror,!, fail. 

nextfield(R,C):- 
field(FNAME, ,ROW,COL, ),gtfield(ROW,R,COL,C), 
chng_actfield(FNAME),!, 
cursor (ROW,COL). 

/* nextfield(_,_). */ 


nextfield(_,_):- 
scr(home). 


gtfield(R1,R2,_, _):-R1>R2,!. 
gtfield(R,R,C1,C2):-C1>C2. 


setlastfield:- 


field(FNAME, ,,_,_), 
chng_actfield( FNAME), 
fail. 

setlastfield. 


Y hniahalaisiahalaialalsialahalalahalalahahaielaheieichelaielahheleieiaielaieialalialsiaialeheisleielslsialaisieialsiaialehlalaial | 


/* scr th 
sAARRAERAERARERARAERERAREERRERAE SETAE EREERERERED SERA TERRARERA ERAN ES J 


/* Insert a mew character in a field */ ’ 
scr(char(T)):-actfield( FNAME), 
not (noinput (FNAME )), 
cursor(_,C), 
field(FNAME, ,ROW,COL,LEN),!, 
POS=C-COL, 
oldstr(FNAME,STR), 
Lin¢(char(T),POS,STR,STR1), 
trunc_(LEN,STR1,STR2), 
ess_val (FNAME ,STR2), 
field_str(ROW,COL,LEN,STR2), 
ser(right). 


/* Delete character under cursor */ 
scr(del):- actfield( FNAME), 
not (noinput(FNAME)), 
cursor(_,C), 
field(FNAME, ,ROW,COL,LEN),!, 
POS=C-COL, 
oldstr(FNAME,STR), 
Lin(del ,POS,STR,STR1), 
ass_val(FNAME,STR1), 
field_str(ROW,COL,LEN,STR1). 


/* Delete character before cursor and move cursor to the left */ 


scr(bdel):- actfield(FNAME), 

not (noinput (FNAME)), 
cursor(_,C), 

field(FNAME, ,ROW,COL,LEN),!, 
POS=C-COL-1, 
oldstr(FNAME,STR), 

Lin(del ,POS,STR,STR1), 
ass_val(FNAME,STR1), 
field_str(ROW,COL,LEN,STR1), 
scr(left). 


/*If there is an action - do it. Otherwise, go to next field*/ 
ser(cr):- 

actfield(FNAME), 

field_action( FNAME), 

cursor(RR,CC),cursor(RR,CC),!. 
scr(cr):-cursor(RR,CC),cursor(RR,CC),scr(tab). 


/* Change between insertmode and overwritemode */ 
scr(ins):-changemode, showoverwrite. 


/* escape */ 
ser( esc ). 


/* F10: end of definition */ 

scr( fkey(10) ):-not(typeerror). 

[RREREEARRARERRER TRANS AAR ERNA AREA LeRA ETA aN aah ane eRe eee 
* Modified 2/5/88 G.Wood 

* added clauses to scr for fkeys 1 thru 9, and new symbolic 
* key 'plus.' Allows these keys to mow be recognized and 
* processed 

RERERERAREREARARARRREARARERERRARRA ARERR ERRRAREARRERRRORRRERE / 
scer( fkey(1) ):-not(typeerror). 

scer( fkey(2) ):-not(typeerror). 

scr( fkey(3) ):-not(typeerror). 

scr( fkey(4) ):-not(typeerror). 


/* 


ser(right):-move_right. */ 


ser(right):- 


cursor(R,C),!, 
nextfield(R,C). 


scr(ctriright):- 


actfield( FNAME), 

not (noinput (FNAME)), 
field(FNAME, ,_,C,L), 
cursor(ROW,COL), 
COL1=COL+5, COL1<C+L-1,!, 
cursor(ROW,COL1). 


ser(ctriright):-move_right. 


scr(left):- 


actfield( FNAME), field(FNAME, ,_,C,_), 
cursor(ROW,COL), 

COL>C,!, 

COL1=COL-1, 

cursor (ROW, COL1). 


scr(left):-move_left. 


ser(ctrlleft):- 


actfield(FNAME), field(FNAME, 
cursor(ROW,COL), 

COL1=COL-5, COL1>C,!, 
cursor(ROW,COL1). 


C,_), 


ao 8 om 


scr(ctrlleft):-move_left. 


scr(tab):- 


cursor(R,C), 
nextfield(R,C). 


scr(btab):- 


cursor(R,C), 
prevfield(R,C). 


scr(up):- 


not(typeerror), 

cursor(R,C), 
best_up(R,C,-100,-100,1,ROW,COL), 
field(F1, ,ROW,COL, ), 
chng_actfield(F1),!, 
cursor(ROW,COL). 


scr(down):- 


not(typeerror), 

cursor(R,C), 
best_down(R,C,100,100,1,ROW,COL), 
field(F1,_,ROW,COL, ), 
chng_actfield(F1),!, 

cursor (ROW,COL). 


scr(home):- 


not(typeerror), 
field(F1, ,ROW,COL, ), 
chng_actfield(F1),!, 
cursor(ROW,COL). 


scr(end):- 


/* scr(fkey(1)):-help. 


not(typeerror), 
setlastfield, 

actfield( FNAME), 

field( FNAME, ,ROW,COL, ),!, 
cursor(ROW,COL). 
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If helpsystem is used. */ 


[RR RII RI RII AAR EIA IIR III III IISA IITA IISA IAA IA ISSA SAID. J 


Te Predicates maintaining the top messages Line *} 
[PARBEERERARRERAERERERERER AER ERREREERAR ERE EEREESESEREERENREREREED f 


mkheader:-notopline,!. 
mkheader: - 
shiftwindow(OLD), 
gotowindow(85), 
field_str(0,0,30, "ROW: 
gotowindow(OLD). 


COLs*); 


PREDICATES 
get_overwritestatus(STRING) 

show_str(COL,LEN, STRING) 

showf ield(ROwW, COL) 


CLAUSES 
get_overwritestatus(insert):-insmode,!. 
get_overwritestatus(overwrite). 


show_str(C,L,STR):- 
windowsize(_,COLS), 
C<COLS,!, 
MAXL=COLS-C, 
min(L,MAXL,LL), 
field_str(0,C,LL,STR). 
show_str(_,_,_). 


showoverwrite:-notopline,!. 
showoverwrite:- 
shiftwindow(OLD), 
gotowindow(85), 
get_overwritestatus(OV), 
show_str(20,9,0V), 
gotowindow(OLD). 


showfield(_,_):-keypressed,!. 
showfield(R,C):- 
field( FNAME, TYP,ROW,COL,LEN), 
ROW=R, COL<=C, C<COL+LEN, 
types(_,TYP,TYPE),!, 
show_str(30,8,TYPE), 
STR=FNAME, show_str(38,42,STR). 
showfield(_,_):-keypressed,!. 
showfield(R,C):- 
txtfield(ROW,COL,LEN, TXT), 
ROW=R, COL<=C, C<=COL+LEN,!, 
show_str(30,1,"\"), 
show_str(31,49, TXT). 
showfield(_,_):-show_str(30,50,""). 


showcursor:-keypressed,!. 
showcursor:-notopline,!. 
showcursor :- 
shiftwindow(OLD), 
cursor(R,C), 
str_int(RSTR,R), str_int(CSTR,C), 
gotowindow(85), 

show_str(4,4,RSTR), show_str(14,4,CSTR), 
showfield(R,C), 

gotowindow(OLD), 

cursor(R,C). 


RII IOI III III II III ITAA RATIO AA III I IIIA IAAI IITA AAI AAI SSIA ISS 


bss update all fields on the screen */ 
LERRRRERERAERERRARERERREERERERRERRERRRERERERERRRRRERREERERERERERES 7 


writescr:- 
field( FNAME, ,ROW,COL,LEN), 
field_attr(ROW,COL,LEN,112), 
field_value(FNAME,STR), 
field_str(ROW,COL,LEN,STR), 
keypressed,!. 

writescr:- 
txtfield(ROW,COL,LEN,STR), 
field_str(ROW,COL,LEN,STR), 
keypressed,!. 

writescr. 


[BRRRERRREEERERARRERRRRERRERERE RA RRREREREREREREEEREEERERREREREE RED / 


/* Shift screen *y 
Vb Can be used if needed */ 
[PARARRERAEREREERERREREREEREREREEREREERRERERRRERREREEARERRRRER AREY 
/* 

PREDICATES 

shiftscreen(SYMBOL ) 


CLAUSES 
shiftscreen(_):-retract(txtfield(_,_,_,_)), fail. 
shiftscreen(_):-retract(windowsize(_,_)), fail. 
shi ftscreen(NAME ):-screen(NAME, TERM), assert(TERM), fail. 
shiftscreen(_). 

ay’ 


LISTING 4: TESTPROG.PRO 


/* Listing 4: TESTPROG.PRO */ 


[RIT IIIA III IAI IA IIIS III IISA IIASA IAI ISAS SII SSSA 


Turbo Prolog Toolbox 
(C) Copyright 1987 Borland International. 


HNDBASIS 
This sample shows the minimum structure of a program using the 


screen handlers. 
RAEREARRREREAEEREREERERARAEAEREREAERREARREERERERRRERRRERRRRARRRRRRE / 


Y halahshahainisiaialahaiaiaisinislaiaisieiaisiainisiaisisiaiaiahaielshaiaielahahaiaiahaisisleishsiaiinialaisialelelsiainisisisisisialal | 


/* Domains e7 
LERAARERERGRRAERARRREAEAREREREREAUERREEREERARERERERAERARARERARERR AEE / 


include "xtdoms.pro" 


OOMAINS 
FNAME=SYMBOL 
TYPE = int(); str(); real() 


Y hahahalaisiaiainiahaiebabaiaiciclaiclsislaialehelaiahaiahaislahslshaisieihaieieheieieishslaisieheiahahehshalaiaiaiaiolelsicieiniaiaiel | 


= Database predicates */ 
[RARRRERARREREREREARRREREERERRRRAERERRERERERRERRRARARERRERRRRERERRED 7 


DATABASE 
/* Database declarations used in scrhnd */ 
insmode /* Global insertmode */ 
actfield( FNAME) /* Actual field */ 
screen(SYMBOL , DBASEDOM) /* Saving different screens */ 
value( FNAME , STRING) /* value of a field */ 
field(FNAME,TYPE,ROW,COL,LEN) /* Screen definition */ 
txtfield(ROW,COL,LEN, STRING) 
windows ize(ROW, COL). 
notopline 


/* DATABASE PREDICATES USED BY VSCRHND */ 
windowstart(ROW,COL) 
mycursord(ROW,COL) 


/* Database declarations used in lineinp */ 
lineinpstate(STRING,COL) 
lineinpflag 


[EARRRRRRERREEERERRREEREEEREREREREREEREEEREREREREREERERRRERERERREERE / 
is Include tools */ 


[III III III III III III III IIIS IIIS II III I IIIS IAI SAI IIASA SSIS 


include "xtpreds.pro" 
include "menu.pro" 

include "status.pro" 
include "Lineinp.pro" 
include "xscrhnd.pro" /* Or vscrhnd.pro */ 


CLAUSES 


BORIC III III IIIT IARI IIA III IA III IIIA IAI IIIS SIS SAISSSS AAS 


Field action 
SERKARARERENEREREERERERERERAREREREREERAERERRERERRERESREREENERRENER Ef 
field_action(_):-fail. 


[RI IA IIR III IR II ASIII IAI IIIA II SAI IIIS ASAI SSSA SSSSAIS IAAI SSA 


Field value 
RHKAERARERRERRERARERERE AERA RERKER ERE EER ERERERE EERE EER ERR EERE EEE 7 


field_value( FNAME ,VAL):-value(FNAME,VAL),!. 
V hololedotatolatatelotetatalohelotetetatatalotelatalatetelotataleiatetatatotaieteielataiehaieiaiaielateietstetataiolsiolsiolsioieisioiel 


noinput 
ERERERAERERREEEAERAEERERRARRERERREREERERRAEREREEREERARERERREREREERE / 


noinput(_):-fail. 


GOAL 
clearwindow, 
consult("test.scr"), 
createwindow(off), 
scrhnd(off,Endkey), 
removewindow, 
write(EndKey). 
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TURBO BASIC 


THE TURBO BASIC/ 
ASSEMBLER CONNECTION 


Write your procedures in Turbo Basic 
to make them work —then rewrite them 
in Turbo Assembler to make them fast. 


David A. Williams 


Turbo Basic is so much faster than inter- 
preted BASIC that you might wonder if 
it’s possible to do better. It 7s possible, and 
the way is through Borland’s new Turbo 
Assembler. If certain key routines are 
—_—v— coded in assembly language and called by 
Turbo Basic, your programs will have considerably 
more zip. This technique gives you the best of both 
worlds—the convenience of Turbo Basic, and the 
speed of assembly language. 


TO THE METAL 


Turbo Basic provides three ways to tap the power of 
assembly language. 


CALL ABSOLUTE. The CALL ABSOLUTE state- 
ment transfers control to an assembly language rou- 
tine that was loaded prior to the call at a specific 
memory location. Although cumbersome, this meth- 
od is available in order to provide a degree of com- 
patibility with interpreted BASIC, where this tech- 
nique originated. There is no reason to recommend 
CALL ABSOLUTE for new programs, and I'll not 
discuss it further in this article. 


CALL INTERRUPT. When used with the REG 
statement and the REG function, the CALL INTER- 
RUPT statement provides access to all DOS and 
BIOS interrupt service routines. This technique has 
a somewhat narrow application, but it does provide 
a way to access certain information that is not other- 
wise available to a BASIC program. (For more infor- 
mation on CALL INTERRUPT, see “DOS Calls From 
Turbo Basic,” TURBO TECHNIX, November/De- 
cember, 1987; and “Calling BIOS Services From 
Turbo Basic,” TURBO TECHNIX, July/August, 1988.) 
Turbo Basic’s most general and powerful assembly 
language interface method involves calls to special 
procedures that are called INLINE procedures. IN- 
LINE procedures may include assembly language 
code in the form of strings of hexadecimal constants, 
or code may be loaded from a machine-code binary 
file at compile time. 


WIZARD 
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INLINE PROCEDURES 


A CALL statement that is used to call an INLINE 
procedure is identical to a CALL statement that is 
used to call any ordinary Turbo Basic procedure. In 
fact, you can design programs with all procedures in 
Turbo Basic, and then replace one or more of the 
procedures with INLINE procedures in machine 
code without changing the main program. 

An INLINE procedure has the following structure: 
SUB <procedure name> INLINE 

$INLINE <byte List> 

$INLINE "filename" 
END SUB 
Here, <procedure name> is the name that is used 
in the CALL statement to call the procedure. The 
$INLINE metastatement may take either a byte list 
of values that represent machine code instructions, 
or else a file of such instructions that exists sepa- 
rately from the Turbo Basic source file on disk. Nor- 
mally you won’t use both of the two forms of the 
$INLINE metastatement in the same procedure (but 
there’s no harm in doing so). A single INLINE pro- 
cedure may contain any number of $INLINE meta- 
statements that specify byte lists. However, you may 
load up to—but not more than—16 binary files 
within a single INLINE procedure by naming each 
file within its own $INLINE metastatement. 


LISTS OF BYTES 


The byte list is a series of values (usually hexadeci- 
mal) that are separated by commas. Each value rep- 
resents one byte of the code that comprises a ma- 
chine instruction. (Machine instructions in Intel’s 86 
family of processors may be anywhere from one to 
six bytes in length, not counting prefixes.) You can 
string as many values behind the $INLINE meta- 
statement as you wish, and there’s no limit to the 
number of $INLINE metastatements that can be 
used within a single INLINE procedure. 


The process of entering code as 
a byte list after an $INLINE meta- 
statement is best used in very 
short programs that contain no 
jump instructions or other branch- 
es. DOS’s DEBUG can perform 
the assembly process, but instruc- 
tions have to be entered one at a 
time to DEBUG, and then the re- 
sulting values must be keyed into 
the INLINE procedure by hand. 
Furthermore, DEBUG cannot con- 
vert labels to addresses, and can 
only treat each instruction in iso- 
lation from all others. Trying to 
hand- or DEBUG-assemble a com- 
plex routine with lots of condi- 
tional branches is the short path 
to insanity, due to the maddening 
difficulty of calculating relative 
jump offsets by hand. 


ENTER TURBO ASSEMBLER 


The better method by far is to 
load a binary file that contains 
machine code that was generated 
with an assembler. The $INLINE 
metastatement can accept a file- 
name that specifies a binary file of 
machine code instructions, as 
shown below: 


SINLINE "MYCODE.BIN" 


This metastatement becomes the 
“beef” of an INLINE procedure. 

It’s beyond the scope of this ar- 
ticle to teach assembly language 
programming. Although Turbo As- 
sembler is fairly new, it’s highly 
compatible with MASM, and 
books previously published for 
MASM programming will help you 
get up to speed. Some tricks will 
make the assemble/link process 
smoother and more automatic. 
The simple batch file below, 
ASM.BAT, automates the process: 
TASM %1; 
TLINK %1; 
DEL %1.0BJ 
EXE2BIN %1 %1.BIN 
DEL %1.EXE 

Execute ASM.BAT by typing the 
following command: 


ASM <filename> 


Here, <filename> is the name of 
the assembly language source file. 
Do not include the source file- 
name extension (i.e., “.ASM”). 
ASM.BAT performs the assembly 
process, the link process, and de- 
letes the superfluous files. ASM 
does leave the .MAP file on disk, 
however, so if you don’t intend to 
use the .MAP information, the 
.MAP file must be deleted. This 
step can be performed manually 


or by the addition of another line 
to ASM.BAT to delete the .MAP 
file. 

ASM.BAT produces memory- 
image binary files with a .BIN ex- 
tension that are ready to load 
through the $INLINE metastate- 
ment. These files can also be 
given a .COM extension; since 
they’re not executable, however, 
the .BIN extension is safer and 
more descriptive. Contrary to the 
instructions in the Turbo Basic 
Owner’s Handbook, do not include 
an ORG 100 directive in the 
Turbo Assembler source files. 


PROBING AN ARRAY 


The rest of this article provides 
two useful examples of assembly 
language extensions to Turbo 
Basic, and explains how those ex- 
tensions are integrated into the 
calling program. Future issues of 
TURBO TECHNIX will present ad- 
ditional assembly language rou- 
tines, along with further discus- 
sions of specific issues such as 
parameter passing and the access 
of global resources. 
MAXDEMO.BAS (Listing 1) 
contains the source code for a 
simple Turbo Basic demo program 
that finds the largest value in an 


continued on page 106 
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THE TURBO CONNECTION 


continued from page 105 


integer array. TBMAX.ASM (List- 
ing 2) is the assembly language 
source code file for the routine 
that MAXDEMO calls to do its 
quick-and-dirty work. MAXDEMO 
first creates the integer array A 
with 100 elements, and then calls 
the Turbo Basic procedure 
GTMAX. This procedure executes 
the machine code routine 
TBMAX to locate the largest value 
in the array. TBMAX executes 
twice as fast as any Turbo Basic 
routine that you could write to 
perform the same function. 

The stack is the key link be- 
tween a Turbo Basic program and 
any assembly language routine. 
All values are passed to machine 
code procedures by reference 
rather than by value. This means 
that the parameter’s data values 
themselves are not passed on the 
stack; instead, an address that 
points to the memory location 
where each value is stored is 
placed on the stack by the com- 
piler. The assembly language rou- 
tine copies the address from the 
stack and uses that address to read 
the value of the actual parameter 
from memory, or else to store a 
value into memory as a means of 
returning a value to the calling 
Turbo Basic program. 

The CALL to GTMAX passes 
three parameters to GTMAX: 
MAXVAL, in which the machine 
code routine passes back the larg- 
est array value; A(1), which is the 
first element of the array; and 
COUNT, which is the number of 
array elements. Since Turbo Basic 
stores array elements in contigu- 
ous memory locations, the entire 
array can be accessed once the to- 
tal number of elements, and the 
address of the first element, are 
known. 

The assembly language routine 
must preserve the values in DS, 
SP, BP, and SS. Any other regis- 
ters may be freely changed. In the 
case of TBMAX, the only critical 
register is BP, which is pushed 
onto the stack. Once BP is safely 
on the stack, TBMAX loads the 


Pointer to Maxval 
offset | BPsoFu 
BP+0EH ——> ES:BX —> ——— 
BP+0DH 
BP+0CH 
Pointer to A(1) 
Pointer to Count 
offset | sPs07i 
= BP+06H ——> ES:BX —> ie ry 
ee ff BP+04H LES instructions are used 
Return address to move the four-byte 
BP+03H pointers to the actual 
parameters into registers 
ae BP+02H ES and DI or BX. Then the 
actual parameters are 
i eal BP+01H accessed through ES: [DI] 
Caller's BP reg. or ES: [BX]. 


Figure 1. The stack as it appears immediately after BP is pushed. 


stack pointer SP into BP. There- 
after, TBMAX accesses its param- 
eters through offsets from BP, 
which now points to the top of the 
stack. 

The stack contains a 32-bit ad- 
dress that points to the memory 
location where each parameter 
value is stored. Figure | shows the 
stack as it exists after the PUSH 
BP instruction. Each “brick” is 
one byte of memory, with high 
memory at the top of the figure. 
The parameters can be accessed 
in any order. In TBMAX, the pa- 
rameter that is accessed first is 
COUNT, which was the last one 
pushed. The LES instruction was 
designed specifically for retrieving 
addresses from the stack: Given 
the offset of the address from BP 
(here, +06H, where the plus sym- 
bol means that the offset is toward 
high memory), LES copies the seg- 
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ment address from the stack into 
ES, and copies the offset address 
from the stack into BX. The MOV 
CX, ES:[BX] instruction copies the 
actual parameter’s value from 
memory into the CX register. The 
same technique is used to gener- 
ate a pointer to the first element 
of array A, but it’s put into DI 
rather than into BX. Since the ar- 
ray count parameter COUNT was 
already moved from memory into 
CX, the original pointer to 
COUNT in BX is no longer 
needed and can be overwritten. 
Hence, the last step is to generate 
a pointer to MAXVAL, and to 
place that pointer into BX until 
it's needed later on. 

The rest of TBMAX compares 
the value of each array element to 
the value in AX. If an array ele- 
ment is found to be larger, that 
element replaces the previous 
value in AX. Because integers are 


16 bits long, TBMAX increments 
DI twice for each pass through the 
loop. (Note: When working with 
long integers or floating point 
numbers, DI must be adjusted ac- 
cording to the size of the base 
type of the array.) After TBMAX 
has examined each element of ar- 
ray A, the value in AX is moved 
into MAXVAL through the point- 
er to MAXVAL that is now in reg- 
isters ES and BX. TBMAX finishes 
the process by popping BP off the 
stack. 

Some notes on TBMAX: The 
same routine works with a multi- 
dimensional array if COUNT con- 
tains the total number of individ- 
ual integer elements in the array. 
Remember, however, that the di- 
mension indexing system starts 
with zero. For example, an array 
dimensioned as A(2,50) has 153 
elements. Also, keep in mind 
when using an INLINE procedure 
that neither the procedure nor the 
machine code routine may con- 
tain RETURN statements. Turbo 
Basic takes care of that step auto- 
matically. 


PASSING STRING 
PARAMETERS 


The process of passing string 
values to assembly language rou- 
tines is a little more subtle. 
SCRNDEMO.BAS (Listing 3) 
shows a Turbo Basic demo pro- 
gram that incorporates Listing 4, 
TBQPA.ASM. TBQPA writes the 
designated string parameter di- 
rectly to display memory at the in- 
dicated row and column location. 
The parameter ATTRIB allows 
changes to be made to the color 
or to other screen attributes of the 
screen area that underlies the 
string to be written. This creates 
very snappy screen displays and 
provides a degree of color control 
that’s not easily achieved with 
standard Turbo Basic statements. 
To keep TBQPA simple, I did not 
include code to prevent video 
snow when using IBM-style CGA 
boards. 


Since strings have a variable 
length, and are stored in a differ- 
ent memory segment than are 
other variables, a different tech- 
nique is needed in order to pass 
string parameters. When a string 
is passed as a parameter, Turbo 
Basic pushes a full 32-bit pointer 
to a “string descriptor” onto the 
stack. The string descriptor consists 
of a two-byte string length counter 
and a two-byte offset into Turbo 
Basic’s string data area (or string 
space). An assembly language rou- 
tine can access a string descriptor 
in the same way that the routine 
accesses a numeric variable. The 
low 16 bits contain the string 
length, and the high 16 bits con- 
tain the offset into string space of 
the first byte of string data. 

The instruction LES BX, 
[BP+12H] sets up ES and BX to 
point to the first byte of the string 
descriptor. The subsequent MOV 
instruction moves the string 
length value into CX. A minor 
complication with the string 
length counter is solved by an 
AND instruction: The high bit (bit 
15) of the string length counter 
has a special meaning to the 
Turbo Basic Runtime code, and 
should not be interpreted as part 
of the string length value. The 
AND instruction masks out bit 15 
to keep it out of later comparisons 
and calculations. Finally, the start- 
ing offset of string data within 
string space is moved into SI, us- 
ing the instruction MOV SI,ES: 
[BX+02]. Note that this offset isn’t 
a full 32-bit address; the segment 
address of string space is still 
needed, and can be found at 
DS:00, which is the first word in 
Turbo Basic’s data segment. A lit- 
tle later in TBQPA, the caller’s DS 
value is pushed onto the stack, 
and then DS is loaded with the ad- 
dress that is found at DS:00. 

In order to move data directly 
into video memory, the location 
of video memory must be known. 
Video memory may be at one of 
two addresses (BOOOH or B800H) 


depending upon which display 
adapter is in use. TBQPA queries 
BIOS interrupt 10H to identify the 
video adapter, sets the address of 
the video buffer accordingly, and 
then moves the string and attri- 
bute data to the video buffer via 

a LOOP structure. When the data 
has been transferred, the routine 
restores the critical registers DS 
and BP, and returns control to the 
calling program. 


NOT SO BASIC BASIC 


TBMAX and TBQPA were kept 
simple to emphasize the interface 
between Turbo Basic and Turbo 
Assembler, rather than the work- 
ings of the assembly language 
routines themselves. Once you un- 
derstand how the two languages 
mesh, you can build on your ex- 
perience and write more ad- 
vanced routines. For example, it’s 
not especially difficult to write as- 
sembly language routines that 
modify string data and then pass 
that data back to the calling pro- 
gram—just remember that you 
can’t change the length of the 
string. If your application requires 
you to change a string length, 
then set up a dummy string of an 
appropriate length first and pass 
the modified string back in the 
dummy string, rather than in the 
original string. 

Numeric processing and screen 
handling are only two of the 
many areas where assembly lan- 
guage can improve the perfor- 
mance of your Turbo Basic pro- 
grams. Take the time to become 
familiar with 86-family assembly 
language—you'll find that BASIC 
is no longer as basic as it was 
when you first typed RUN. @ 


David A. Williams is a principal staff 
engineer for a major aerospace com- 
pany. He can be reached at 2452 
Chase Circle, Clearwater, FL 34624. 


Listings may be downloaded from 
Library 1 of CompuServe forum 
BPROGA, as TBTASM.ARC. 
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| LISTING 1: MAXDEMO.BAS 


cLS 

DEFINT A-Z 

DIM AC100) 

RANDOM! ZE(157) 

FOR I=1 TO 100 
A(1)=10000*RND(9) 

NEXT 

MAXVAL=0 

COUNT=100 

CALL GTMAX(MAXVAL ,A(1), COUNT) 

PRINT MAXVAL 

END 


SUB GTMAX INLINE 
SINLINE “TBMAX.BIN" 
END SUB 


LISTING 2: TBMAX.ASM 


;TBMAX.ASM Routine to find max value in integer array 
CODE SEGMENT 
ASSUME CS:CODE ,DS:CODE 
PUSH BP 7Save BP 
MOV BP, SP ;Get stack address 
;Get the arguments 
LES BX, [BP+06H) 7Get addr of array count 
MOV CX, ES: [BX] 7Put count in CX 
LEs DI, [BP+OAH) jGet addr of first element 
LES BX, [BP+0EH) 7Get addr of return value 
7Find the max value 
AX,ES: [DI] 7Get first array element 
AX,ES:(DI+2] | ;Compare present with next 
8 
AX,ES: (D1+2) 7Put new, larger value in AX 
DI 
DI 
A 
ES: [BX] , AX 
7Clean up and leave 
QUIT: POP BP 
CODE ENDS 
END 


;Store max value 


;Restore BP 


LISTING 3: SCRNDEMO.BAS 


cLs 

DEFINT A-Z 

AS="THIS IS A TEST" 

ROW=16 

COL=15 

ATTRIB=7 

CALL WRT CAS, ROW, COL ATTRIB) 

CALL WRT("Another test",5,20,15) 

CALL WRT(LEFTS(A$,8)+"ALSO GOOD", 10,40, 7) 
END 


SUB WRT INLINE 
SINLINE "TBQPA.BIN" 
END SUB 


LISTING 4: TBQPA.ASM 


;TBQPA.ASM Fast screen write routine for Turbo Basic 


CODE SEGMENT 


ASSUME CS: CODE ,DS:CODE 


PUSH BP 
MOV BP,SP 
7Get arguments 

BX, [BP+0AH] 
D1,ES: (BX) 
DI 
BX, [BP+OEH) 
AX, ES: [BX] 
AX 
BX, [BP+12H] 
CX, ES: (BX) 
CX, 7FFFH 
cx, 00 
QUIT 
SI,ES: (BX+02)] 


;Compute offset into video buffer 


MOV DX, 0050H 
MUL Dx 
ADD DI,AX 
SHL DI,1 
;Get video parameters 
BX, [BP+06) 
BX, ES: [BX] 
AX, OBOOOK 
ES,AX 
AH, OFH 
10H 
AL,7 
A 
AX, OB800H 
ES, AX 
A: os 
;Copy data to video buffer 
MOV DS,DS: [00] 
CLD 
MOVSB 


;Save BP 
;Get stack address 


7Get addr of Col variable 
Put Col number in DI 
7Change Col # to 0 - 79 
Get addr of Row variabie 
7Put Row # in AX 

Change to 0 - 25 

7Get addr of string pointer 
Put string length in CL 
7Remove high bit 

zis it zero? 

7Yes, quit 

;Put string start addr in SI 


Num of char per row 
7# rows times 80 
7Add column number 
Multiply by 2 


7Get address of attribute 
7Put attribute in BX 
7Video buffer addr, mono 
;Put it in ES 

yRead video mode 


zIs it mono? 


7Video buffer addr, mono 
Put it in ES 
7Save DS on stack 


Get string segment 
7Clear direction flag 
7Send 1 byte to buffer 


MOV BYTE PTR ES:(D1],BL ;Attribute byte 


INC DI 

Loop B 
;Clean up and leave 

PoP DS 
QUIT: POP BP 
CODE ENDS 

END 


7Skip attribute byte 
jLoop until done 


7Restore DS 
Restore BP 
;TB runtime handles return 
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Basically speaking, there's 
one choice ... Turbo Basic! 


Turbo Basic 


Edit | Compile to 


Turbo Basic’s development environment gives you overlapping windows, pull down menus, and the ability 


to run text-based applications in a window. 


Turbo Basic® is the BASIC that 
lets even beginners write polished, 
professional programs almost as 
easily as they can write their names. 

The others don’t. When you 
really examine them, you'll find 
that even though they may be 
““quick,’’ they make it hard to 
get where you're going. (Sort of 
like a car with an engine but no 
steering wheel.) 

Turbo Basic takes you farther 
faster—in the comfort of a sleek 
development environment that 
gives you full control. Naturally 
it has a slick, fast compiler just like 
all Borland’s technically superior 
Turbo languages. It a/so has a full- 
screen windowed editor, pull-down 
menus, and a trace debugging 


System Requirements: For the [BM PS/2™ and the |BM® family of personal 
computers and all 100% compatibles. Operating System: PC-DOS (MS-DOS) 
2.0 or later. Toolboxes require Turbo Basic 1.1. Memory: 384K RAM for 


compiler, 640K RAM to compile Toolboxes. 

*Customer satisfaction is our main concern: if within 60 days of purchase this 
product does not perform in accordance with our claims, call our customer 
service department, and we will arrange a refund 


jarks of Borland International, Inc. Other 


ve holders. Copyright ©1988 Borland 
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system. And innovative Borland 
features like binary disk files, true 
recursion, and more control over 
your compiling. Plus the ability to 
create programs as large as your 
system's memory can hold. 

The critics agree. The choice is 
basic. Turbo Basic from Borland. 


¢6¢ ... What really makes 
Turbo Basic special is its blind- 
ing speed, small size, and many 
added commands. Programs 
compiled with Turbo Basic are 
often much faster and smaller 
than those produced by other 
compilers. 


Ethan Winer, PC Magazine Best of 1987 


Turbo Basic, simply put, is an 
incredibly good product. 
William Zachman, Computerworld 99 


Add another Basic advantage: 
The Turbo Basic Toolboxes 


¢ The Database Toolbox gives 
you code to incorporate into 
your own programs. You don’t 
have to reinvent the wheel every 
time you write new Turbo Basic 
database programs. 


¢ The Editor Toolbox is all 
you need to build your own 
text editor or word processor, 
including source code for two 
sample editors. 


New! 


New! 


60-Day Money-back Guarantee* 


Compare the BASIC differences! 


Turbo Basic 1.1 


Compile & Link to 


stand-alone EXE 2 ae 
Size of .EXE 28387 
Execution time . 

0.16 sec. 
w/80287 16 sec 
Execution time 0.16 sec. 


w/o 80287 


QuickBASIC 4.0 QuickBASIC 4.0 


Compiler Interpreter 
7 sec. -— 
25980 — 

16.5 sec. 21.5 sec. 

286.3 sec. 292.3 sec. 


The Elkins Optimization Benchmark program from March 1988 issue of Computer Language was used. 
The Program was run on an IBM PS/2 Model 60 with 80287. The benchmark tests compiler’s ability to 
optimize loop-invariant code, unused code, expression and conditional evaluation. 


For the dealer nearest you 
call (800) 543-7543 


TURBO BASIC 


COMMAND LINE PARAMETERS 
IN TURBO BASIC 


Divide the command line string 


into parameters — 


and conquer your Turbo Basic command line 


entry problems. 


Duke Kamstra 


The ability to read parameters that are 
entered on the DOS command line is a 
powerful feature in any application or 
utility program. Users have come to ex- 
pect applications to read information 
such as filenames from the command line 
when a language compiler or database is invoked. 
The Turbo Basic Integrated Development Environ- 
ment is a good example. When entered at the DOS 
command line, the following command invokes 
Turbo Basic and loads the file PARAM.BAS into the 
editor: 

TB PARAM 


PROGRAMMER 


This example only uses one command line param- 
eter, but many programs accept two or more. The 
widely used ARC utility, which is sold by System En- 
hancement Associates (Wayne, New Jersey) uses sev- 
eral command line parameters. The following exam- 
ple shows a typical invocation of ARC51.EXE: 


ARC51 A COML.ARC *.BAS *.EXE DESCRIPT.CIS 


This example command line contains five individual 
parameters, which are separated from one another 
by spaces. 


BRINGING THE COMMAND LINE HOME 


Most language compilers have some means of read- 
ing the command line parameters that are used by 
programs written in those languages. Turbo Basic’s 
COMMANDS$ function returns all of the command 
line parameters concatenated into one string. This 
is a good start; however, the information in the com- 
mand line string isn’t really useful until the string 
has been separated into its individual parameters. 
When accessing command line parameters, a pro- 
gram needs access to two pieces of information: the 
number of parameters that were entered, and the 
values of the individual parameters themselves. 
While Turbo Basic provides the command line 
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string, the process of counting and separating the 
parameters that make up the string must be handled 
with additional code. In PARAM.BAS (Listing 1), I’ve 
provided the Turbo Basic function FNParam- 
Count%(), which returns the number of parameters; 
and FNParamStr$(), which returns individual pa- 
rameters by number. 

If you’ve done some Turbo Basic programming, 
PARAM.BAS should not be difficult to understand. 
FNParamCount%() handles the bulk of the work for 
both functions. When FNParamCount%() is called 
for the first time, it divides the command line string 
into individual parameters, and then stores the pa- 
rameters in the global array Parameters$(). At the 
same time, FNParamCount%() counts the number of 
parameters that it stores, and saves that count value 
in the STATIC variable Result%. Result% becomes 
the value returned by FNParamCount%() to the call- 
ing program. After the first time it’s called, FNPa- 
ramCount%() does not need to process the com- 
mand string any further; when called again, FNPa- 
ramCount%() simply returns the value it already 
stored in Result%. 

FNParamCount%() separates parameters by scan- 
ning for separator characters (which may be either 
spaces or double quotes) in the string that is re- 
turned by COMMANDS. Each time FNParam- 
Count%() finds a separator, the left and right char- 
acter positions of the found parameter are recorded 
in a two-dimensional integer array, ParamPos%(). 
ParamPos%() contains up to 25 pairs of integers 
(each integer pair consists of a left and a right char- 
acter position value). This limits the number of pa- 
rameters that may be extracted from the command 
string to 25. Since DOS limits the size of the com- 
mand string to 127 characters, however, the maxi- 
mum of 25 parameters should not be a crippling 
limitation. Once the initial scan for separators is 
complete, FNParamCount%() loops through the 
command string a second time, and copies the 


continued on page 112 


LISTING 1: PARAM.BAS 


Author: Duke Kamstra 
Mod. Date: 5/8/88 


To use these routines in your own program, keep them in an 
include file. When you need to manage command line parameters 
in a program include these routines by inserting the 
metastatement: 

SINCLUDE “PARAM" 
in your program. Be sure to set the named constant 
XMAXPARAMETERS appropriately for your application. If the 
number of parameters given on the command line is larger 
than X%MAXPARAMETERS the extras are ignored. 


*MAXPARAMETERS = 25 ' Maximum # of parameters that can be read by the 
* program. Should never be larger than 64 since 
* DOS only allows a 127 character command line. 
DIM Parameters$(0:%MAXPARAMETERS) ' String array used to store 
‘ parameters 
%TRUE = 1 ' Named constant representing boolean value 
DEF FNParamCount% 
Return the number of command line parameters passed to the program. 
Store each of the parameters in the SHARED string array 
Parameters$(). Note the function will only process up to 
XMAXPARAMETERS command line parameters. 


The first time the function is called it processes the parameter 
list and sets a flag Initialized% to indicate that the command 
line doesn't need to be processed again. Any subsequent calls to 
the function will return the value stored in Result. 
STATIC Initialized% ' Flag indicating parameters have been read 
' and data structure has been initialized. 
STATIC Result% ' Store result after calling the function 
' the first time 
SHARED Parameters$() ' Global variable to store parameter data 


LOCAL 1%, J%, Count%, ParamPos%(), SearchChar$ 


mL = ' Named constants used to reference ParamPos% 
MR = 


DIM ParamPos%(0:%MAXPARAMETERS, %L:%R) ' Make room for position 
' information 


IF Initialized&% <> XTRUE THEN ' We haven't parsed the command 
' Line yet 
' Set flag indicating we've parsed the command line 
Initialized% = XTRUE 
IF COMMANDS = "" THEN ' No command line parameters specified 
FNParamCount% = 0 ' Return O for parameter count 
Result% = 0 ' Save parameter count in static variable 
EXIT DEF ' Leave the function 
ELSE ‘ At least one command line parameter was specified 
' First we need to determine the number of parameters 
x =1 
WHILE (1% <= LEN(COMMANDS)) AND (Count% < XMAXPARAMETERS) 
Count% = Count% + 1 ' Increment parameter counter 
ParamPos%(Count%, %L) = 1% ' Store left position of parameter 
' Determine what to search for as the end of the current 
' parameter 
IF MIDS(COMMAND$,1%,1) = CHR$(34) THEN 
' Parameter is enclosed in double quotes 
SearchChar$ = CHR$(34) 
ParamPos%(Count%, %L) = _ ' we don't want the " 
ParamPosx(Count%, %L) + 1 


ELSE 
SearchChar$ =" " 
END IF 
' Check if the next character in the command line terminates 
' the current parameter 
IF INSTR(1X%+1,COMMANDS,SearchChar$) <> 0 THEN 
' find end of parameter 
1% = INSTR(1%+1, COMMANDS, SearchChar$) 
' Store right position of parameter 
ParamPos%(Count%, %R) = 1% 
' Advance past the " 
IF SearchChar$ = CHRS$(34) THEN IX = IX + 1 
ELSE 
* Store right position of parameter 
ParamPosX(Count%, %R) = LEN(COMMANDS) + 1 
EXIT LOOP 
END IF 
WHILE MIDS(COMMAND$,1%,1) = ™ “ AND IX < LEN(COMMANDS) 
IX = 1X +1 * mow find the start of the next parameter 
WEND 
WEND 


* look for a space 


' mext we need to store the parameters in our SHARED string 
: pa 
array 


FOR JX = 1 TO Count% ' Store each of the parameters 
Parameters$(J%) = MIDS(COMMANDS, ParamPos%(J%, XL), _ 
ParamPos%(J%, %R) - ParamPosX(J%, %L)) 
NEXT J% 
FNParamCount% = Count% 
Result® = Count% 
END IF * COMMANDS = "" 
ELSE ' The function has already been called once 
FNParamCount% = Result% 
END IF 
END DEF ' FNParamCount% 


DEF FNParamStr$(Count%) 

' Return the command line parameter indexed by Count%. The function 
' verifies that the parameter exists by calling FNParamCount%(). If 
' the parameter exists it is read from the global SHARED array 

' Parameter$() and returned. 


SHARED Parameters$() ‘' Global variable to store parameter data 
LOCAL ParmCount% 


IF Count% <= FNParamCount% THEN ' Check to make sure parameter 
FNParamStr$ = Parameters$(Count%) ' exists 
ELSE 
FNParamStr$ = "" 
END IF 
END DEF ' FNParamStr$() 


LISTING 2: PARMDEMO.BAS 


‘ Author: Duke Kamstra 
' Mod. date: 5/8/88 
' 
' This program demonstrates the subroutines FNParamCountX() and 
' FNParamStr$(). 
' 
' Compilation instructions: 
' I. In the Turbo Basic Integrated Development Environment: 
‘ a. Load the program into the Turbo Basic editor. 
- b. In the Options\Parameter Line menu define a command 
L line parameter List. For example: 
: this is a "test parameter list" 
, c. Press ALT-R to run the program in memory. 
' Il. From a .EXE file: 
8 a. Load the program into the Turbo Basic editor. 
5 b. In the Options\Compile to menu select EXE file. 
c. Press ALT-C to compile PARAM.BAS to PARAM.EXE. 
U d. Press ALT-F Q@ to leave the Turbo Basic Integrated 
7 Development Environment. 
u e. At the DOS command line type: 
4 PARAM this is a “test parameter list" 
SINCLUDE "PARAM" ' Include the command line parameter routines 
cLS 
PRINT FNParamCount%;" parameters were passed to PARMDEMO" 
PRINT "The parameters are:" 
FOR 1% = 1 TO FNParamCount% 
PRINT "Parameter# ";1%,FNParamStr$(1%) 
NEXT I% 
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PARAMETERS 
continued from page 110 


parameters out into the Parameters$() string array 
by using the left and right character positions stored 
in ParamPos%(). 

FNParamStr$() is much simpler. It first calls 
FNParamCount%() to make sure that the calling pro- 
gram hasn’t asked for a nonexistent parameter. If 
the requested parameter exists, that parameter is 
read from the string array Parameters$() and re- 
turned as the function return value. If the requested 
parameter does not exist, no error is generated, but 
FNParamStr$() returns an empty string. 


TRYING IT OUT 


The file PARMDEMO.BAS (Listing 2) demonstrates 
the use of FNParamCount%() and FNParamStr$(). 
PARMDEMO simply $INCLUDEs the file PA- 
RAM.BAS and calls the two functions to display any 
parameters that are passed to PARMDEMO upon 
PARMDEMO’s invocation. To try the demo program, 
load PARMDEMO.BAS into Turbo Basic’s Integrated 
Environment and then compile it to an .EXE file. 
Next, exit Turbo Basic, and invoke PARM- 
DEMO.EXE with one or more command line 
parameters: 


PARMDEMO fee fie foe fum 


PARADISE PRICES 


e GREAT PRICES: SUPER. 
SERVICE AND UNBEATABLE: 
AVAILABILITY! 


CALL PROGRAMMER’S PARADISE TODAY and dis- 
cover the best software at the best prices. You'll find software 
pros to help you select the products you need. Immediate 
shipment on our stock of over 1000 products with a 30-day 
money back guarantee. 


Basic 

Gack Basic 

db/Lib 

Finally! 

Finally! X Graf 

Quick Windows 
w/Source 

Quick Pak | 

Quick Pak Professional 

Grafpak Professional 


C Language 

C Tools Plus/5.0 
Greenleaf TurboFunctions 
Quick C (Microsoft) 


Panel QC or TC 
Periscope II X 
Turbo C Tools 
Turbo Halo 
Cbtree 


Pascal Language 

Microsoft Pascal 3.0 

Tdebug Plus 4.0 
w/Source 

Turbo Async Plus 

Turbo Geometry Library 

Turbo Halo 

Turbo Magic 

Turbo Plus 5.0 
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The PARMDEMO program immediately summarizes 
the parameters, as shown in the following sample 
output: 


4 parameters were passed to PARMDEMO 
The parameters are: 


Parameter# 1 fee 
Parameter# 2 fie 
Parameter# 3 foe 
Parameter# 4 fum 


The PARMDEMO program calls FNParam- 
Count%() to determine how many parameters were 
passed to PARDEMO, and then calls FNParamStr$() 
to read each of the individual parameters. 

Note that your program may call either of the 
functions in either order, and as often as necessary. 
The call to FNParamCount%() in FNParamStr$() as- 
sures that if FNParamStr$() is called first, the com- 
mand line parameters are still processed and stored 
in Parameters$(). Either way, the parameters will be 
there when you need them. @ 


Duke Kamstra is a quality assurance coordinator for 
Borland International, Inc. 


Listings may be downloaded from Library 1 of Compu- 
Serve forum BPROGA, as TBCOML.ARC. 


Turbo Power Utilities 
Turbo Professional 4.0 
Turbo Window/Pascal 


Topaz 
Turbo Analyst 


Borland Products 
Eureka 

Reflex: The Analyst 
Sidekick 

Sidekick + 

Superkey 

Turbo Basic Compiler 
Turbo Basic Database 
Turbo Basic Editor TB 
Turbo Basic Telecom TB 


Source Print 
Tree Diagrammer 
Magic P 
Desqview 
Norton Guides 
4 ba Al T y 
HOW WE WORK 
PHONE ORDERS Hours 9 AM-7 PM 
EST. We accept MasterCard, Visa, 
American Express. Include $3.95 per 
item for shipping and handling. All 


shipments by UPS ground. Rush service 
available. 


MAIL ORDERS POs by mail or fax 
are welcome. Please include phone 
number. 


Turbo C 

Turbo Lightning and 
Lightning Word Wizard 

Turbo Pascal 

Turbo Pascal Dbase Toolbox 

Turbo Pascal Dev. Toolkit 

Turbo Pascal Editor Toolbox 

Turbo Pascal Gameworks TB 

Turbo Pascal Graphix TB 

Turbo Pascal Num. Methods 

Turbo Pascal Tutor 

Turbo Prolog Compiler 

Turbo Prolog Toolbox 


Additional Products 
Lahey Personal Fortran 
Smalltalk/V 
Smalltalk/286 

Multi-Edit 

Poly Awk 


INTERNATIONAL SERVICE Call 
or fax for information. 

DEALERS AND CORPORATE 
ACCOUNTS Call for information. 
UNBEATABLE PRICES we'll 
match lower nationally advertised 
prices. 

TECHNICAL SUPPORT FROM 
SOFTWARE PROS 

RETURN POLICY 30-day no-hassle 
return policy. Some manufacturer's 
products cannot be returned once disk 
seals are broken. 

In NY: 914-332-4548 

Customer Service: 914-332-0869 
International Orders: 914-332-4548 
Telex: 510-601-7602 

Fax: 914-332-4021 


0-15-89 


NTF rs 


A Division of Oro Software Corp. 
55 South Broadway, Tarrytown, NY 10591 


GETTING IN THE LOOP 


LOOP is the key to repeating blocks of statements 


without using GOTO. 


Tom Wrona 


One of the key facets of structured pro- 
gramming is the art of making loops. 
While structured programming is permitted 
by the syntax of BASIC, and encouraged by 
certain Turbo Basic features, BASIC (un- 
oa like Pascal) does not require structured 
programming. Thus, if your first programming lan- 
guage is BASIC, you might not fully appreciate the 
significance of loops in structured programming. 
When using interpreted BASIC, it’s all too easy to 
produce what professional programmers call “spa- 
ghetti code”: meandering, unstructured code that’s 
hard to understand and hard to debug. The two 
prime spaghetti code influences in BASIC are the 
language’s reliance upon line numbers, and its prim- 
itive looping abilities. Turbo Basic, however, corrects 
both problems. First of all, line numbers aren’t re- 
quired in Turbo Basic; in fact, you should never use 
them. Period. Second, Turbo Basic’s looping facilities 
are much more sophisticated than interpreted 
BASIC’s good old FOR..NEXT, as I'll explain in 
this article. 


SQUARE ONE 


BEYOND FOR..NEXT 


FOR..NEXT only permits a block of statements to be 
repeated some number of times. Listing 1 is a min- 
imal program that illustrates how FOR..NEXT works, 
and shows the loop’s use of the STEP keyword to in- 
crement the loop counter by a number other than 
one. Run this listing and watch what it does. While 
FOR..NEXT is useful, more powerful looping con- 
structs are needed for writing commercial-quality 
software. 

When you first start programming, it’s a little dif- 
ficult to see what your modest efforts have in com- 
mon with commercial programs such as WordStar or 
Lotus 1-2-3. You begin by learning that a program is 
a list of instructions that are executed sequentially by 
the computer; your own programs contain sequential 
lists of Turbo Basic commands. However, when you 
start up an advanced application such as MicroCalc 
(the spreadsheet program that is included with 
Turbo Basic), you notice that its commands don’t 


seem to be very sequential—the program is just there, 
on the screen, all at once. 

All programs, MicroCalc included, are thoroughly 
sequential—this becomes apparent when you look 
closely at the nature of the sequence. Listing 2 shows 
a short program that is very similar to programs writ- 
ten by most BASIC programmers while they’re get- 
ting their feet wet. The program begins, executes 
some statements, and stops, producing the output 
shown in Figure 1. The text lines shown in Figure | 
appear on the screen, one after the other, as the pro- 
gram executes each program line. 

Figure 2 is a screen “snapshot” of the MicroCalc 
screen that appears when MicroCalc executes. Com- 
pare Figure 1 with Figure 2. Rather than appearing 
to be the result of a sequence of instructions, Micro- 
Calc seems to be just “there” all at once, awaiting 
input. 

The operative word here is “awaiting.” By the time 
MicroCalc has drawn the spreadsheet grid and be- 
gins waiting for our input (in this case, a number, a 
letter, a cursor movement key, or a slash command), 
the program has already done a lot of preparatory 
work and is in the middle of a loop. Examine Listing 
3, which shows the source code for MicroCalc’s main 
program. We can pinpoint the exact location in the 
code when the program seemingly pops up on the 
screen all at once. (I’ve added numbers to the print- 
ed listing for reference purposes; these numbers are 
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Let's play with numbers! 

Pick a number and I'Ll tell you facts about it. 
What's your number? 42 

The square root of your number is 6.48074069840786. 
Want to know something else (Y/N)? Y 

A circle with a diameter of 42 would have 

a circumference of 131.88. 

That's all! Thanks for playing! 


Figure 1. Programs written by newcomers often present a 
simple, linear question-and-answer session such as the one 
shown here. A repeating command loop offers a great deal 
more sophistication with respect to how a program com- 
municates with the user. 
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TURBO BASIC 


[A1, Text] 


GETTING IN THE LOOP 


Type / for Commands, F2 for Edit 
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not present in the actual MC.BAS 
file.) Line 67 is the comment line 
shown below: 


‘set up a LOOP UNTIL '/Q' command 
is chosen 


Immediately after this line, a 
DO..LOOP begins that deter- 
mines which key has been 
pressed by the user. (I'll discuss 
DO..LOOPs in more detail 
shortly.) This DO..LOOP, which 
is the main body of the program, 
shunts the flow of the program to 
the subroutine that is invoked by 
the keypress. Everything above 
line 67 in the program is prepara- 
tion for the DO..LOOP. Lines 58- 
65 check if a filename (of a pre- 
viously saved spreadsheet) has 
been typed in after the “MC” on 
the command line; if the filename 
was entered, then the subroutine 
Load is CALLed to load that 
sheet; otherwise (ELSE), a blank 
spreadsheet is drawn by CALLing 
the Grid subroutine. Subroutines 
such as Grid are contained in var- 
ious include files, which are part 
of MicroCalc. 


PSEUDO-CODE 


One way to understand a pro- 
gramming problem is to think in 
terms of “pseudo-code.” Pseudo- 
code is an English-language 
“sketch” of a program that you 
create before you get down to the 
job of coding in your actual pro- 
gramming language. (For more on 


futoCalc is ON 


pseudo-code, see “Binary Engi- 
neering,” TURBO TECHNIX, No- 
vember/December, 1987.) 
Pseudo-code is useful not only 
for creating a program, but also 


for analyzing an existing program. 


One good way to increase your 
understanding of program struc- 
ture is to reverse-engineer a pro- 
gram’s source code back to 
pseudo-code. For example, the 
pseudo-code equivalent of the 
code from the beginning of the 
program to the start of the main 
loop at line 68 is shown below: 
Initialize all variables 

and arrays (CALL Init) 

IF a filename was typed in... 

CALL the spreadsheet file 

loading subroutine. 
No filename? (ELSE) 
CALL Grid to draw 
a blank spreadsheet. 
That's all, go on. (END IF) 

The main loop extends from 
the DO keyword in line 68 to 
LOOP UNTIL CalcExit% in line 
93. This main loop, called a 
DO..LOOP, is one kind of control 
structure. 


CONTROL STRUCTURES 
Control structures such as 
DO..LOOPs are a language’s 
method for determining which 
instructions get executed, based 
upon the value of a variable or 
the occurrence of an event. Not 
all control structures are loops. 
For example, an IF..THEN condi- 
tional test is used to determine if a 
spreadsheet file should be loaded. 


Figure 2. The command menu from 
the MicroCalc spreadsheet, shown 
here, uses a loop to repeatedly test the 
keyboard until a command character 
is entered. Once a character is detected, 
the program executes the command 
represented by that character. 


The logic of such a test is very 
English-like: IF the filename ex- 
ists, THEN CALL Load to load it, 
ELSE draw a blank spreadsheet. 
Although multiple tests can be 
performed using IF..THEN, each 
test occurs only once. Thus, 
IF..THEN is a one-way action, not 
a loop. 


The DO..LOOP statement. While 
both IF..THEN statements and 
DO..LOOP statements always in- 
volve testing, DO..LOOPs are 
used more as processing tools, in- 
stead of testing tools. Again, the 
name DO..LOOP reflects the 
function of these keywords in an 
English-like fashion: The program 
will DO some process UNTIL or 
WHILE some expression is true 
or false. 

What MicroCalc’s main 
DO..LOOP does (and, therefore, 
what the program spends most of 
its time doing) is nothing more 
than waiting for keyboard input. 
When such input appears, the 
program processes the keyboard 
input to see what should be done 
next. MicroCalc keeps on process- 
ing keyboard input until a “/Q” 
is entered to terminate the pro- 
gram. 

Calling ReadK BD. The main 
loop’s first action (at line 69) is to 
CALL a little subroutine called 
ReadKBD. ReadKBD, which is 
reproduced in Listing 4, tells its 
caller which key has been pressed. 
What is ReadKBD? Another loop, 
of course. ReadKBD’s loop is the 
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MAGIC PC ELIMINATES CODING . .. CUTS MONTHS OF DATABASE DEVELOPMENT! 


Time is money. And coding a DBMS 
application like Accounting or Order 
Entry takes a lot of both. Simply be- 
cause hacking out mountains of code 
with your RDBMS or 4GL is too 
slow. Not to mention the time to re- 
write if you make a mistake or change 
the design. 


EXECUTION TABLES 
ELIMINATE CODE! 
Magic PC cuts months of your appli- 
cation development time because it 
eliminates coding. You program with 
the state-of-the-art Execution Tables 
in place of conventional programming. 


HOW DOES IT WORK? 
Magic PC turns your database design 
scheme directly into executable appli- 
cations without any coding. Use Exe- 


cution Tables to describe only what 


your programs do with compact design 
spec’s, free from lengthy how to pro- 
gramming details. Each table entry is 
a powerful non-procedural design in- 
struction which is executed at com- 
piled-like speed by a runtime engine. 
Yet the tables can be modified “on the 
fly” without any maintenance. De- 
velop full-featured multi-user turn- 
key systems with custom screens, 
windows, menus, reports and much 
more in days — not months! No more 
low-level programming, no time 
wasted... 
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MAGIC PC 


The Database Language 
zane “Magic PC’s database en- 
[ish gine delivers powerful app- 
lications in a fraction of 
the time... there is nocom- 
petitive product.” 

[y7_} “Overall, Magic PC is one 
i a h of the most powerful DBMS 

packages available.” 


® Quick Application Generator 

@ BTRIEVE® — based multi-user RDBMS 
© Visual design language eliminates coding 
®@ Maintenance-free program modifications 
® Easy-to-use Visual Query-By-Example 
® Multi-file Zoom window look-ups 

® Low-cost distribution Runtimes 

®@ OEM versions available 


ATTENTION BTRIEVE® USERS 
Now you can quickly enhance your BTRIEVE®- 
based applications beyond the capabilities of 
XTRIEVE® and RTRIEVE®. Use Magic PC as 
aturn-key BTRIEVE® Application Generator to 
customize your applications without even chang- 
ing your existing code. 


re 
rT AY 
19782 MacArthur Boulevard, Suite 305 
Irvine, California 92715 
TLX: 493-1184 FAX: 714-833-0323 
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DATABASE PROGRAMMERS 
Join the thousands of professional 
database programmers and vertical 
market developers who switched to 
Magic PC from dBase®, R:BASE®, 
Paradox®, Clipper®, Dataflex®, Rev- 
elation®, Basic, C, Pascal, etc. 


TRY BEFORE YOU PAY 


We're so sure you'll love Magic PC — 
we'll let you try the complete package 
first. Only a limited quantity is avail- 
able, so call us today to reserve your 
copy. Pay for Magic PC only after 30 
days of working with it.* To cancel... 
don’t call... simply return in 30 days 
for a $19.95 restocking fee. 


OR PAY NOW AT NO RISK 
Pay when you order and we’ll wave 
the $19.95 restocking fee so you have 
absolutely no risk. 


SPECIAL OFFER 695 3695 


199 2. 


Magic LAN i— a — $399 
Magic RUN — call for price 


Order Now Call: 
800-345-MAGIC 


In CA 714-250-1718 


i te 
Add $10 P&H, tax in CA. International orders add $30. 
*Secured with credit card or open P.O. Valid in US. 
Dealers welcomed 
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Paradox 2.0, the top-rated 
Network, 386, and 


Paradox is both the first family in 
DBMS and the top-rated relational 
database. Software Digest has 
ranked Paradox *1 for the past 

2 years; PC Magazine gave Paradox 
its ““Editor’s Choice’’ award and 
InfoWorld named it 1987 *‘Product 
of the Year’’ for Database Systems. 


Now there’s OS/2 


Paradox OS/2 is the newest 
member of the Paradox family— 
more are on the way and they're all 
100% compatible with each other. 

Paradox OS/2 allows you to take 
advantage of powerful OS/2 fea- 
tures such as addressing up to 16 
megabytes of memory and running 
concurrent sessions. And Paradox 
OS/2 even lets you start new OS/2 
sessions from within Paradox. 


*Customer satisfaction is our main concern; if within 60 days of purchase this 
product does not perform in accordance with our claims, call our customer 
service department, and we will arrange a refund 

All Borland products are trademarks or registered trademarks of Borland International. Inc. Other 


brand and product names are trademarks of their respective holders. Copyright ©1988 Borland 
International, Inc BI 1228A 
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Harness the power of 386 


Paradox 386 is powerful new 
DOS software for your powerful 
new hardware and it’s designed 
exclusively for 80386-based sys- 
tems. It also lets you ignore the old 
640K limits and races through your 
data 32 bits at a time instead of just 
16. It’s a perfect solution for 
anyone faced with very large tables 
(tens of thousands of records or 
more) and/or large applications. 


66 As proof of Borland’s commit- 
ment to delivering compatibility 
across diverse hardware and soft- 
ware environments, Paradox 386 
and Paradox 2.0 can share the 
same databases and applications 
on a network. 

Giovanni Perrone, PC Week 


Paradox ... it’s the PC database- 

management system equivalent to 

turbo-charging an M-series BMW. 
Giovanni Perrone, PC WEEK 95 
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The Paradox Network 
really works 


Network users, you need 
Paradox’s multiuser capabilities. 
The network runs smoothly, intelli- 
gently and so transparently that 
multiusers can access the same 
data at the same time—without 
getting in each other’s way. (But 
safeguards prevent multiple users 
from altering the same data at the 
same time.) And with screen 
refresh you get real-time data 
updates on your screen. 


66 [Paradox is] a true network 
application, a program that can 
actually take advantage of a net- 
work to provide more features and 
functions, things that can’t be done 
with a standalone PC. 

Aaron Brenner, LAN Magazine 


|Paradox] elegantly handles all 
the chores of a multiuser database 
system with little or no effort by 
network users. 


Mark Cook and Steve King 
Data Based Advisor 99 


relational database, has 
now OS/? versions! 
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“Query-by-Example” gives you 
the right answer, right now 

Our ‘‘Query-by-Example’’ (QBE) 
technique is just one illustration of 
the technological leadership offered 
by Paradox for the past 2 years. 

QBE is fast and simple to use. 
Simply call up a form and check off 
the information you want. 


{ (F6) to include a field in the QRMER; (F5) to give an txample ,/)/ 
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hobok~valet 
Mink handkerchiefs (13) 
Rabot-valet 


Without having to write a line of 
code, you can, for example, get an- 
swers to queries like: Find all the 
items we sold for more than $1000 
and tell me who ordered them. 

An artificial intelligence tech- 
nique called ‘heuristic query 


optimization’’ gives Paradox's OBE 
the ability to figure out not just the 
right answer, but also the fastest 
way to get the right answer. 

QBE makes high-speed links 
between one piece of data and 
another and quickly sees the rela- 
tionships your question calls for. 


PAL” A powerful 
programming language 

PAL, the Paradox Application 
Language, is a full-featured, high- 
level, structured database program- 
ming language that lets you write 
sophisticated Paradox programs 
(scripts) and applications. It in- 
cludes such powerful features as 
looping constructs, arrays, branch- 
ing, procedures, and a full set of 
functions. 


66 Most people we meet who 
give Paradox a try, end up 
switching to it... 
Mark Cook and Steve King 
Data Based Advisor 9 


There’s a Paradox 2.0 
version for you 


Whether you're a DOS or 
OS/2 user, there's a Paradox 
version for you. 


60-Day Money-back Guarantee* 


For a brochure or the dealer nearest 
you, call (800) 543-7543 


INTERNATIONAL 
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gateway into MicroCalc, the re- 
ceiving dock where the characters 
come when they’re shipped out of 
the keyboard by the user’s fingers. 
Below are the two statements con- 
tained in ReadKBD, along with a 
pseudo-code explanation of each: 


STATEMENT: RetChar$ = 
INKEY$ 


PSEUDO-CODE: Request a char- 
acter from the keyboard (IN- 
KEY$) and place it in the function 
return variable (RetChar$). 


STATEMENT: LOOP UNTIL 
RetChar$< >”” 


PSEUDO-CODE: Keep requesting 
a character from the keyboard un- 
til the character that you get 
(stored in RetChar$) is an actual 
character and not a null string 
(2”): 

Essentially, ReadKBD is a 
keyboard-input processing ma- 
chine that receives characters 
from the keyboard and places 
them into the program. Why is an 
input processing loop necessary 
when INPUT can be used? Be- 
cause when INPUT executes, it in- 
variably puts that dumb question 
mark on the screen—this is fine 
for a quick and dirty program, but 
inappropriate for professional- 
quality programs that you can 
write with Turbo Basic. 


Loops within loops. ReadKBD’s 
presence in the main loop is a 
perfect illustration of the “loop 
within a loop” type of program- 
ming. Both ReadKBD and the 
main loop are DO..UNTIL loops. 
In this kind of loop, the process- 
ing statements are repeated 
UNTIL the test condition is true. 
In the case of ReadKBD, the 
clever construction UNTIL- 
RetChar$ <>”” means that un- 
less the program has something 
else to do, it remains in its tight lit- 
tle loop, checking the keyboard 
for characters. Given the relative 
slowness of humans and the 
speed with which the machine 
can process their input, it’s safe to 
say that MicroCalc spends over 90 
percent of its time executing this 
one line! 


In the main loop, the test con- 
dition is LOOP UNTIL Calc- 
Exit%. Although CalcExit% is an 
integer (this is indicated by the 
presence of the percent sign), it’s 
used here as a Boolean variable 
that can be interpreted as either 
True or False. In the Command 
subroutine, which interprets slash 
commands, there is a SELECT 
CASE statement that assigns Calc- 
Exit% with a value of True if 
“/Q” has been pressed. (Just as 
DO..LOOP is FOR..NEXT’s big 
brother, SELECT CASE is 
IF..THEN’s big brother. For more 
on SELECT CASE, see “SELECT 
CASE: Choosing One From the 
Many,” TURBO TECHNIX, 
March/April, 1988.) 


Where to test? In both ReadKBD 
and the main loop, the condition 
is tested at the bottom of the loop. 
However, testing can be perform- 
ed at the top of the loop, at the 
top and the bottom of the loop, or 
at neither. If testing is not done at 
either the top or the bottom of the 
loop, the loop is then endless and 
repeats forever, unless an exit is 
performed somewhere in the mid- 
dle of the loop via a GOTO state- 
ment (bad practice), or else via the 
EXIT LOOP statement (infinitely 
better) as shown below: 
DO 

GetSomeI nput(InputPresent%) 

IF NOT InputPresent% 

THEN EXIT LOOP 

ProcessInput 
LOOP 

Testing at the top of the loop is 
simple to perform, as demon- 
strated by the following code: 


QuitProcess% = 0 


DO UNTIL QuitProcess% 

DoSomeWork 

AreWeDoneYet (Qui tProcess%) 
LOOP 

The logical opposite of a 
DO..UNTIL loop is a DO..WHILE 
loop. In a DO..WHILE loop, the 
processing operation is repeated 
WHILE the condition is true. The 
operation of a DO..WHILE loop 
is shown below: 
GetSomeI nput ( InputPresent%) 
DO 

ProcessInput 

GetSomeI nput(InputPresent%) 
WHILE InputPresent% 
Notice that the presence of the 
keyword WHILE at the bottom of 
the loop makes the LOOP key- 
word unnecessary. 


Another syntax for DO..WHILE 
is called WHILE..WEND; this syn- 
tax is borrowed from older ver- 
sions of BASIC. WHILE..WEND 
tests at the top of a loop, as dem- 
onstrated in the following code: 


GetSomeI nput (InputPresent%) 


WHILE InputPresent% 
ProcessInput 
GetMore!I nput(InputPresent%) 

WEND 

WHILE..WEND is completely 

equivalent to DO..WHILE; 

whether you use it or not is strictly 

a matter of taste. 


ONWARD 


To learn how to write commercial- 
quality software, you have to un- 
derstand how it differs from the 
toy programs that we all write 
when starting out. With Turbo 
Basic, an important first step is to 
understand structured program- 
ming and control structures such 
as DO..LOOP statements. Where 
do you go from here? Try studying 
the source code for MicroCalc. 
Print it out and follow the pro- 
gram flow into the various include 
files and their procedures and 
functions. Rewrite MC.BAS as 
pseudo-code to get some more in- 
sights into how large programs 
are put together. Identify useful 
subroutines like ReadKBD that 
you can use and reuse in your 
own projects. Obtain public do- 
main programs that include 
source code, and study the code 
with a critical eye. Is the code 
sloppy or tight? Is it spaghetti code 
or well-commented structured 
code? 

The more source code that you 
study, and the more that you write 
yourself, the better you'll become 
at programming in Turbo Basic. 
And someday, perhaps, the com- 
mercial program that pops up on 
my screen will be yours. 


Tom Wrona is a writer, consultant, 
and the author of How to Run a 
Hard Disk PC, published in March 
by Scott, Foresman & Company. 
Reach Tom via CompuServe 
(76137,3363) or MCI Mail. 


Listings may be downloaded from 
Library 1 of CompuServe forum 
BPROGA, as LOOPS.ARC. 
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LISTING 1: FORTEST.BAS 


‘A simple program demonstrating FOR. .NEXT 
' with the STEP modifier: 


FOR i = 2 to 8 STEP 2 
Print i 
NEXT i 
PRINT "Who do we appreciate?" 


LISTING 2: NUMBERS.BAS 


‘Toy Program by Tom Wrona 


cLs 

PRINT “Let's play with numbers!" 

PRINT “Pick a mumber and I'll tell you facts about it." 
INPUT "What's your number"; number 

PRINT "The square root of your number is " SQR(number)"." 
INPUT "Want to know something else (Y/N)" answers 

IF UCASES(answer$) = "N" GOTO DONE 

PRINT "A circle with a diameter of"number"would have 
PRINT "a circumference of" 3.14 * number"." 

DONE: 

PRINT "That's all! Thanks for playing!" 


LISTING 3: MC.BAS 


1 ' 

ae MC.BAS 

as VERSION 1.0 

4 ‘ 

a Turbo Basic 

e" (C) Copyright 1987 by Borland International 

iA ' 

8 '| System Requirements: 

ry - DOS Version 2.0 or later 

10! - 320K 

1 

12 '| This program is a simple spreadsheet program that is provided 
13. '| as an example of a simple application that can be done in 
14 '| Turbo Basic. You are encouraged to study this program and 
15 '| make any enhancements and modifications that you might want. 
a 

22 

23 SOYNAMIC ' ALL arrays are DYNAMIC 

24 $STACK 10240 ' to prevent stack overflow 

25 

26 SINCLUDE "MCO.INC" ' Global variables, named constant AND 
27 ' array definition 

28 

29 SINCLUDE "MC1. INC" ' Miscellaneous commands AND utilities 
30 ' (Keyboard, screen, toggles) 

31 

32 SINCLUDE "MC2.INC" ' Init, display & clear spreadsheet grid 
33 

34 SINCLUDE "MC3.INC" ' Display Cells; move around spreadsheet 
35 

36 SINCLUDE "MC4.INC" ' Load, Save AND Print a spreadsheet; 
37 ' display on-line manual; DOS shell 

39 


40 SINCLUDE "MC5.INC" ' Procedures to evaluate formulas AND 


41 ' recalculate the spreadsheet 

42 

43 SINCLUDE "MC6.INC" ' Procedures to read, update AND format 
4 ' cells; Commands dispatcher 

45 

46 SINCLUDE "MC7.INC" ' Some string functions 

47 


48 SINCLUDE "MC8.INC" ' Procedures to Read/Write records to or 
49 ' from the spreadsheet data structure 
52 RANDOMIZE TIMER ' init random number generator 

53 Begintimer=TIMER ' initial time 


55° ————____——— MAIN. PROGRAM)_ 


57 CALL Init 

58 FileName$=FNGetCmdS 

59 IF FNExistsX%(FileName$) THEN 

60 CALL load 

61 ~ELSE 

62 cLS 

63 CALL Grid 

64 CALL GotoCel l(GlobFX%, GlobFY%) 
65 END IF 


67 ' set up a LOOP UNTIL '/Q' command is chosen 
68 DO 

69 CALL ReadKBD(Ch$) 

70 CALL IBMCh(Ch$) 

71 SELECT CASE left$(Ch$,1) 


72 CASE CHR$(5) val 
73 CALL MoveUp 
7% CASE CHR$(24), CHR$(10) rox, os 
le) CALL MoveDown 
76 CASE CHRS(4), CHR$(13) ie hs 
CALL MoveRi ght 
CASE CHR$(19) Jaks 
CALL MoveLeft 
CASE CHRS(1) ok 
CALL MoveHome 
CASE CHRS$(6) Jel 
CALL MoveEnd 
CASE "/" ' Command Header 
CALL Commands 
CASE CHRS(XEditKey ) al 4 
CALL GetCell(GlobFxX%, GlobFY%) 
CASE ELSE 


IF ( left$(Ch$,1) >= "" ) AND ( left$(Ch$,1) <= CHR$(255)) 
THEN CALL GetCell(GlobFX%, GlobFYX) 
END IF 
END SELECT 
LOOP UNTIL CalcExit% 


RRRASLESELRALAKSSIA ar 


END MAIN PROGRAM —————-—___1 


LISTING 4: READKBD.BAS 


"ReadKBD, a subroutine contained in MC1.INC 


SUB ReadKBD(RetChar$) 
' This function reads a keystroke from the keyboard 
' and returns 1- OR 2-character string. 


Lee) 
RetChar$ = INKEYS 
LOOP UNTIL RetChar$<>"" 


* get the keyboard input 


END SUB 
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PROFESSIONAL TOOLS 


TURBO ASSEMBLER: 
CIVILIZING MACHINE 


LANGUAGE 


If you’ve never tackled the 86-family’s own pmemaae, 


this may be the Ideal time to start. 


Tom Swan 


You’ve probably heard The Famous 

Truths About Assembly Language—‘“Pro- 

gramming in assembly language is more 
ie difficult than teaching buffaloes to 

pirduette;” “An assembly language pro- 
sounpow*e.— gram can trash memory faster than Oliver 
North can shred a sensitive document;” and, “Only 
13-year-old software prodigies can understand as- 
sembly language mnemonics!” 

These are bad raps. Assembly language is not a 
great deal more difficult to learn and to use than any 
other computer language. This is especially true now 
with the availability of new features such as Ideal 
mode, local labels, and improved command-line op- 
tions in Turbo Assembler—Borland International’s 
newest Turbo language and the partner of Turbo De- 
bugger. If you’re eager to learn assembly language, 
you couldn’t have picked a better time to begin. 

Turbo Assembler is not just for beginners, though. 
If you’re an experienced assembly language pro- 
grammer, you'll be happy to know that Turbo As- 
sembler is fully compatible with the Microsoft Macro 
Assembler (MASM). Turbo Assembler recognizes all 
MASM macros, conditional assembly and other di- 
rectives, plus simplified segment models. If you have 
existing assembly language programs to maintain, 
Turbo Assembler can almost certainly assemble them. 

Of course, Turbo Assembler carries the famous 
Borland mark of the gazelle—it assembles a 2000- 
line test file in less than four seconds on a 16-mHz 
80386 system (about twice as fast as MASM 5.1). And, 
like MASM, Turbo Assembler supports all typical PC 
processors (8088, 8086, 80186, 80286, 80386) and 
math coprocessors (8087, 80287, 80387). 

Other features make Turbo Assembler friendly to 
use. For example, the following command assembles 
all of the .ASM files in a directory: 

TASM *.ASM 

Turbo Assembler’s most intriguing new feature, 
called Ideal mode, is a logical refinement to standard 
MASM syntax. If you’re new to assembly language 
programming, Ideal mode will help you get up to 


SQUARE ONE 


120 TURBO TECHNIX September/October 1988 


speed without getting 

bogged down in minor syntac- 
tical quirks that plague other assemblers (especially 
MASM). If you’re an old pro (or a young pro!), you'll 
appreciate Ideal mode’s many improvements to 
MASM syntax, plus the ability to switch back to full 
MASM compatibility at any time and assemble exist- 
ing modules written in the standard syntax. I'll cover 
Ideal mode in more detail shortly. 

First, however, a note to beginners: If assembly 
language is still gobbledygook to you, skim over the 
specific examples in this introduction. I’ve tried to 
provide general information for those of you with lit- 
tle or no assembly language experience, but there 
isn’t enough room here for a complete tutorial. For 
help with learning assembly language, refer to the 
Turbo Assembler manual, other TURBO TECHNIX 
articles, and forthcoming books on Turbo Assembler. 
[Editor’s note: Including one by the estimable Mr. 
Swan.] 


USING TURBO ASSEMBLER 

Unlike other Turbo languages, Turbo Assembler is not 
an integrated development environment with a text 
editor and pull-down menus. Instead, Turbo Assembler 


“Operates from 
= the DOS command 
~ line, similar to the way ~ 
ASM runs. Turbo Assembler 
requires the use of a separate 
Peciior for typing programs, and most 
~ people probably will use the editor in Turbo C, 
Turbo Pascal, Turbo Basic, or Turbo Prolog. Other 
good choices are the MicroStar editor in the Turbo 
Pascal Editor Toolbox, or the notepads in SideKick 
and SideKick Plus. You can also use an editor such as 
Brief (my favorite), or any word processor that edits 
plain ASCII text. 

Many people will use Turbo Assembler with one 
or more high-level Turbo languages to convert se- 
lected BASIC subroutines, Pascal procedures, or C 
functions to assembly language in order to gain the 
extra speed that only pure machine code can give. In 
fact, experts estimate that most programs spend 
about 90 percent of their time executing only 10 per- 
cent of their code. In theory, therefore, the conver- 
sion of the critical 10 percent of any program to as- 
sembly language potentially increases program 
speed by almost as much as could be done by rewrit- 
ing the entire program. 

To help you mix and match Turbo Assembler with 
other Borland languages, individual chapters in the 
Turbo Assembler manual explain how to interface 
assembly language to Turbo Pascal, Turbo C, Turbo 
Basic, and Turbo Prolog. Turbo C can even call 
Turbo Assembler directly to assemble inline assem- 
bly language statements embedded in Turbo C 
source text. 

Of course, standalone programs can also be as- 
sembled with Turbo Assembler. Programs can be lo- 
cated in one file, or else divided into modules, as- 
sembled separately, and then linked with other 
modules to create the final code file on disk. Since 


bo As ible i is fully 
fle with MASM, you can take 
lage of fhe thousands of lines of 
"published assembly language source code 
available on bulletin boards, in magazines and 
Boks, and elsewhere. 


QUIRKS MODE 


Through a special command, Turbo Assembler can 
even reproduce known MASM bugs and quirks. To 
use this command, type QUIRKS into your source 
text to throw Turbo Assembler into quirks mode for 
near 100-percent MASM source code compatibility, 
warts, bugs, and all. 

The only MASM programs that Turbo Assembler 
cannot digest are a few rare (and poorly written) ex- 
amples that rely on MASM’s two-pass nature. Turbo 
Assembler is a one-pass assembler—it reads a pro- 
gram text file a single time in order to generate an 
object file that contains the assembled program code. 
MASM reads a program text file twice—once to iden- 
tify labels, and once again to generate the object 
code. With respect to speed, one pass is obviously 
better than two. Besides, you're better off not using— 
and never writing—finicky two-pass-dependent pro- 
grams in the first place. 


IDEAL MODE—ENTER STAGE RIGHT 


Besides MASM compatibility (with or without quirks), 
Turbo Assembler introduces [deal mode—this depar- 
ture from MASM syntax is a subject that’s bound to 
be controversial among bit-twiddlers everywhere. 
Ideal mode is to assembly language what Hamlet 
and other Shakespearean plays were (and are) to 
English—the sensible and inventive force that civi- 
lizes an existing language. Shakespeare didn’t create 
English. He improved and expanded the language in 
ways that have lasted until today and that will no 
doubt endure for as long as English itself. Similarly, 
Turbo Assembler’s Ideal mode improves MASM syn- 
tax in ways that are likely to have long-lasting effects 
on PC assembly language programming. Ideal mode 
is not just a new assembly language syntax—Ideal 
mode has refined, reformed, and civilized MASM. 


New and improved syntax. Ideal mode improves 
MASM syntax in two fundamental areas: consistency 
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TURBO ASSEMBLER 
continued from page 121 


and type-checking. An improved consistency among 
commands helps you to remember syntax rules, and 
lets Turbo Assembler use simpler parsing methods to 
read and understand programs. Due to its simpler 
parsing rules, Ideal mode assembles programs about 
30 percent faster than they can be assembled in 
MASM mode. That’s 30 percent faster than Turbo 
Assembler’s own MASM-compatible mode, which is 
already twice as fast as MASM itself! 


Keywords. In Ideal mode, most keywords begin an 
instruction, rather than appearing in the apparently 
random fashion that they do in MASM. Table 1 com- 
pares several Ideal mode keywords to their MASM 
equivalents. Notice that ENDP and ENDS are option- 
ally followed by the name of the procedure or seg- 
ment that was previously used in a matching PROC 
or SEGMENT directive. (In MASM, the name pre- 
cedes the keyword and, therefore, must be used in 
both places.) 


MASM Mode Ideal Mode 

name ENDP ENDP [name] 
name ENDS ENDS [name] 
name GROUP segs GROUP name segs 
name LABEL type LABEL name type 


name MACRO args 
name PROC type 
name RECORD args 


MACRO name args 
PROC name type 
RECORD name args 


name SEGMENT args SEGMENT name args 
name STRUC STRUC name 
name UNION UNION name 


Table 1. Ideal mode versus MASM keywords. Bracketed 
items are optional. 


Type-checking. Ideal mode’s stronger type-checking 
rules help you write programs that have fewer bugs 
and make more sense both to you and to the assem- 
bler. When assembling in Ideal mode, for example, 
Turbo Assembler never lets addresses be confused 
with values stored in memory (this is a prime source 
of bugs even with experienced programmers). Ideal 
mode also eliminates MASM’s annoying tendency to 
calculate some offsets relative to individual segments 
that are collected by the GROUP command. In Ideal 
mode, items in grouped segments are always ac- 
cessed relative to the group, not to the segment in 
which the items reside. 

Pascal and C programmers know that strong type- 
checking helps prevent bugs by restricting assign- 
ments and other operations to variables of compat- 
ible types. With Turbo Assembler’s Ideal mode, 
assembly language programmers can now enjoy sim- 
ilar benefits with no loss of capability and no penalty 
on program speed. 


IDEAL MODE AND BRACKETS 


An excellent example of how Ideal mode’s stronger 
type-checking rules help prevent bugs is the way that 
square brackets (e.g., []) are required in order to ob- 
tain the contents of a memory location. For example, 
[MyVar] with brackets refers to the contents stored 
in memory at the location marked by the label, 
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MyVar. This rule has important consequences in 
constructions such as the following: 


Count dw 0 


mov ax, [Count] 


Here, Count is a label (a pointer) that locates a 
two-byte word in memory, which is initialized to zero. 
(The dw stands for “define word.”) The second line 
moves the contents of Count into register ax. Be- 
cause of the brackets, there’s no question that 
[Count] refers to the contents of the memory loca- 
tion and not to the value of the Count label itself. 
Contrast this with the following: 


mov ax, Count 


MASM allows this ambiguous construction. (So 
does Turbo Assembler in MASM mode, of course.) 
The instruction seems to be loading Count into ax. 
But that’s silly. Count is a label, a 32-bit address com- 
posed of 16-bit segment and offset values—and 32- 
bit labels cannot be loaded into 16-bit registers. Only 
16-bit values can be loaded into 16-bit registers, and 
only 8-bit values can be loaded into 8-bit registers. 
Since it knows that this instruction is senseless, 
MASM assumes that you must be trying to load ax 
with the contents stored at the address of Count and, 
therefore, happily assembles the program as though 
you had written mov ax,[Count] with brackets! 

Turbo Assembler in Ideal mode properly warns 
that you probably forgot the brackets around Count. 
Ideal mode can do this because it checks that the 
type of the destination (ax) is compatible with the 
source (Count). 

When you do want to load the value of a label intc 
a register, you must specify which type-compatible 
part of the label is to be used. To assign the 16-bit 
offset value of the label Count to ax, relative to the 
segment that declares the label, you must write: 


mov ax, OFFSET Count 


Both Turbo Assembler (in all modes) and MASM 
correctly assemble this instruction. When the pro- 
gram runs, the 16-bit offset address of Count is 
moved (copied) into ax. The danger here—and the 
reason that Ideal mode rejects the bracketless con- 
struction—is that you might easily forget to type the 
OFFSET keyword when referring to the label’s ad- 
dress. If you do this in MASM, the assembled code 
mistakenly refers to the contents stored at this ad- 
dress, and you won’t know something is wrong until 
the program begins to misbehave. Turbo Assembler’s 
Ideal mode spots this and other subtle mistakes dur- 
ing assembly, thus helping you to write programs 
that run as you intend. Unlike MASM, Ideal mode 
never tries to decide what you “really” mean! 


OTHER IDEAL-MODE FEATURES 


Another important Ideal-mode feature is a new job 
description for a useful assembly language employee— 
the lonely dot. In MASM, dots have many jobs. Dots 
begin some directives (.LIST and .RADIX), but not 
others (INCLUDE and COMM). Dots separate struc- 
tures, as in CUSTOMER.ADDRESS. Dots are used in 
floating point numbers (5.2) and in some commands 
(.386) that look like numbers, but aren’t. It’s enough 

to drive you batty, if not dotty. 


The Ideal dot. In Turbo Assembler’s Ideal mode, 
dots never begin keywords. Period. Dots always sep- 
arate identifiers in structures and unions, and mark 
the decimal places in floating point numbers. 

Since no Ideal-mode keyword begins with a dot, 
some MASM directives are necessarily different, as 
shown in Tables 2 and 3. For instance, the MASM 
command .286 (which enables 80286-processor in- 
structions) is P286 in Ideal mode. Ideal mode com- 
mands that begin with percent signs, such as %LIST 
and %NOCREF, affect program listings. These 
changes help clarify programs and make them easier 
to read. In Ideal mode, you always know a command 
when you see one. Even better, you don’t have to 
hunt through the manual to find out whether a com- 
mand requires a leading dot. 


MASM Mode Ideal Mode 
-.CREF %CREF 
-LALL %MACS 
LFCOND %CONDS 
LIST %LIST 
SFCOND %NOCONDS 
-XALL %NOMACS 
XCREF %NOCREF 
XLIST %NOLIST 


Table 2. Ideal mode versus MASM listing controls. 


MASM Mode _ Ideal Mode MASM Mode Ideal Mode 
186 P186 ERR2 ERRIF2 
286 P286N ERRB ERRIFB 
.286C P286N -ERRDEF ERRIFDEF 
-286P P286 -ERRDIF ERRIFDIF 
.287 P287 -ERRDIFI ERRIFDIFI 
386 P386N -ERRE ERRIFE 
.386C P386N -ERRIDN ERRIFIDN 
386P P386 -ERRIDNI ERRIFIDNI 
387 P387 -ERRNB ERRIFNB 
8086 P8086 -ERRNDEF ERRIFNDEF 
8087 P8087 ERRNZ ERRIF 
-FARDATA FARDATA .CODE CODESEG 
-FARDATA? UFARDATA .CONST CONST 
-MODEL MODEL DATA DATASEG 
-RADIX RADIX DATA? UDATASEG 
.ERR ERR STACK STACK 
.ERRI ERRIF1 


Table 3. Ideal mode versus MASM dot commands. 


Nesting and field names. Ideal mode structures and 
unions can also be nested (this is an illegal opera- 
tion in MASM). In addition, field names that are in- 
side one structure can be the same as the field 
names that are inside another structure. The ability 
for two or more structures to have the same field 
names is especially helpful during the manipulation 
of linked lists with many structures, where all link 
fields in various records are named something like 
NextRec and PrevRec. MASM requires unique 
names to be invented for fields in all records, even 
when the fields have identical purposes. 


PROGRAMMING IN IDEAL MODE 


Other major differences between MASM and Ideal 
modes are best described by example. Listing | is an 


Ideal mode program that displays a disk directory. 
This program incorporates a single directory “search 
engine” that is similar to the search engines for 
Turbo Pascal and Turbo C presented elsewhere in 
this issue. 

To create and run DR.EXE, use the following 
commands: 

TASM DR 
TLINK DR 
DR 

After an initial comment line in the listing, the 
keyword IDEAL initiates Ideal mode. Although not 
shown here, the keyword MASM can be used to 
switch back to MASM compatibility. This lets you al- 
ternate between the two modes in the same listing as 
often as you like. 

Because the %TITLE directive begins with a per- 
cent sign, you know that this command affects listing 
output. Notice that a comment line (the text that fol- 
lows the semicolon) is allowed because the title 
string in Ideal mode must be enclosed in quotes. To 
create a listing file, assemble the program with the 
following command: 


TASM /L DR 


To generate a cross-referenced symbol table at the 
end of the listing, use this command instead: 


TASM /C/L DR 


Table 4 lists other command-line options that can be 
used during assembly. 
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TURBO ASSEMBLER 
continued from page 123 
Option Description 
/A Order segments alphabetically 
/C Add cross-reference to listing file 
7D Define a symbol 
7E Emulate floating point instructions 
/H Display command-line syntax help 
/I Set include-file path 
/J Define a startup directive 
7L Generate a listing file 
/ML Treat symbols as case-sensitive 


/MU Convert symbols to uppercase 

/MX Make public and external symbols case-sensitive 
/N Suppress symbol table in listing file 

rag Check for impure code 

/8 Specify sequential segment-ordering 

LE Suppress messages on successful assembly 

/W Enable warning messages 

7X Include false conditionals in listing 


/Z Display lines containing errors 
Enable line-number information in object file 
Enable debugging information in object file 


Table 4. Turbo Assembler command-line options. 


The DOSSEG, MODEL, and STACK commands 
select the Small memory model, which is a good 
choice for most standalone assembly language pro- 
grams. Table 5 lists other memory models that can 
be used in both Ideal and MASM modes. 


Model Description 


Tiny Code, data, and stack in one 64K segment. 
Subroutine calls and data references are 
near. Use for .COM files only. 

Code and data in separate 64K segments. 
Subroutine calls and data references are 
near. Use for most .EXE files and small- to 
medium-size programs. 

Unlimited code size. Data limited to one 64K 
segment. Subroutine calls are far; data ref- 
erences are near. Use for large programs 
with minimal data. 

Code limited to one 64K segment. Unlimited 
data size. Subroutine calls are near; data ref- 
erences are far. Arrays limited to 64K. Use 
with small- to medium-size programs with 
many or very large variables. 

Unlimited code and data sizes. Subroutine 
calls and data references are far. Arrays 
limited to 64K. Use for largest program and 
data storage requirements, as long as no sin- 
gle variable exceeds 64K. 

Unlimited code and data size. Subroutine 
calls and data references are far. Arrays not 
limited in size. Pointers to array elements 
are far. Use for largest programs where one 
or more variables exceed 64K. 


Table 5. Turbo Assembler memory models. 


Small 


Medium 


Four equates (which use the EQU directive) asso- 
ciate constant values with the identifiers: Attribute, 
FileName, Cr, and Lf. During assembly in Ideal 
mode, equates are stored as text. As a result, expres- 
sions are not evaluated until the program uses the 
equated identifier. At that time, the associated text re- 
places the identifier in a process similar to the oper- 
ation of a macro. In the sample listing, the equates 
are simple numbers. Suppose, however, that you 
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have the following equates: 


c = 4; 
Value EQU C+10; 
G = 9; 


In MASM mode, Value equals 14 because Turbo As- 
sembler evaluates the expression C+10 when read- 
ing the EQU declaration. In Ideal mode, Turbo As- 
sembler evaluates C+10 at the place where the Value 
identifier later appears in a program statement. The 
difference is important. Because the second equate 
redefines C to 9, Value in Ideal mode equals 19, not 
14 as it would in MASM mode. (Here, an equals sign 
is the same as EQU, but allows the value associated 
with an identifier to be changed.) In Ideal mode, you 
can be certain that C+10 uses the value of C because 
C exists at the place in the program where the 
equated identifier appears. 

In Listing 1, DATASEG defines the program’s data 
segment, which is the memory storage area for vari- 
ables. Two of these variables are strings. FileSpec, 
which is an ASCIIZ string that ends with a zero byte, 
holds the directory search wildcard (identical to wild- 
card expressions such as *.PAS or TEST.* in DOS 
DIR commands). The program uses CrLf (a peculiar, 
although common, kind of DOS string that ends with 
a dollar sign) to display blank lines. The third vari- 
able, DTA, reserves 128 bytes for the DOS directory 
search functions. 

The program’s code segment begins at the key- 
word CODESEG. The comments to the right of each 
line describe the assembly language instructions. No- 
tice how OFFSET keywords specify label addresses. 

The DATASEG and CODESEG keywords demon- 
strate Turbo Assembler’s simplified memory seg- 
ments. (Similar keywords are available in MASM 
mode.) You can always define segments the hard way 
by using SEGMENT directives, as required in early 
versions of MASM. Most times, however, you can use 
the simplified directives and select an appropriate 
memory model from Table 5. 


PROCEDURES AND LOCAL LABELS 


Assembly language procedures, which are optionally 
delimited by the PROC and ENDP directives, resem- 
ble BASIC subroutines more than Pascal procedures 
or C functions. As Listing 1 shows, the name follows 
the PROC directive in Ideal mode; MASM reverses 
this order. 

Notice the labels @@t10:, @@t20:, and @@t30: 
inside DirSearch. Farther down, two of these same 
labels appear again. After a LOCALS directive (not 
required in Ideal mode), labels that begin with @@ 
are local to the portion of the program that is sepa- 
rated from the rest of the program by nonlocal labels. 

Local labels, which can be used in both Ideal and 
MASM modes, have two main purposes. A local label 
can define a temporary destination for a jump, such 
as the jmp @@t10 instruction in procedure Dir- 
Search. More importantly, a local label can also elim- 
inate the worry that you may have used the same 
label in another part of the program. The use of lo- 
cal labels avoids the annoying MASM error “Symbol 
already defined,” because unique labels no longer 
have to be invented for every last destination in your 
program. 


Local labels are not merely convenient, however. 
They can also help prevent serious bugs by restrict- 
ing short jumps to small sections of code. For exam- 
ple, if you misspell or forget to define the @@t10: 
label in procedure DirSearch, the jmp @@t10 in- 
struction cannot accidentally jump into the middle of 
the next procedure, which also contains a label 
@@tl10:. The bug is prevented because the nonlocal 
label ListDir lies between the local label @@t10: 
and the jmp @@t10 instruction. 


AN ASSEMBLY LANGUAGE SEARCH ENGINE 


Listing 1 contains a procedure, DirSearch, that 
searches the current directory for a given file spec- 
ification (which may contain wildcard characters) 
and a file attribute byte. DirSearch uses the DOS 
Find First and Find Next functions (as described in 
“A Directory Search Engine in Turbo C” on page 74 
of this issue). To use DirSearch, extract the proce- 
dure DirSearch from the program and include it into 
your own program. Call DirSearch with ds:dx ad- 
dressing a null-terminated file specification string. If 
you desire, assign a set of attributes to cx that limits 
directory entries to those entries that are marked 
with the Archive, Hidden, or other flags. Otherwise, 
set cx to zero to ignore file attribute settings. 

Assign to bx the code-segment offset of a proce- 
dure to be called by DirSearch each time a matching 
file is found. The corresponding procedure in List- 
ing | is ListDir, which simply transfers one filename, 
a character at a time, to the standard output through 
DOS function 2. In your own procedure, you might 
further examine the filename or other information 
stored in DTA and take appropriate action. (Consult 
a DOS reference for the offsets to various directory 
items.) For example, filenames could be transferred 
to an array and a sorted directory displayed later in- 
side a window. Or, you could search for two different 
filename endings and list all *.EXE and *.COM files 
(a fancy pattern-matching scheme that DOS cannot 
provide from its command line). The choices are 
limited only by your imagination. 

After all, isn’t that the reason why you've decided 
to learn—or why you're already using—assembly 
language? Like no other programming language, 
assembly language offers the most flexibility for the 
implementation of your software dreams. 

If you’ve been meaning to learn assembly lan- 
guage, or if you're tired of fighting MASM’s crock of 
quirks, take a look at Turbo Assembler and try a few 
examples in Ideal mode. I think you'll be pleased. 
Undoubtedly, some MASM fans will hear about Ideal 
mode and say, “If it ain’t broke, why fix it?” I say, 
“It’s been broke all along, and the repair truck has 
finally arrived.” 


Tom Swan is the author of Mastering Turbo Pascal 4.0, 
Second Edition (Howard W. Sams). Barring World War 
III or, even worse, a coffee bean shortage, Tom’s new book, 
Mastering Turbo Assembler, will be available early in 
1989. 


Listings may be downloaded from Library 1 of Compu- 
Serve forum BPROGB, as TADIR.ARC. 


LISTING 1: DR.ASM 


77> Display disk directory. Written by Tom Swan in Turbo Assembler. 


IDEAL ; Switch on Ideal mode 
XTITLE = “OR.ASM" ; Comments allowed in titles! 
; Use standard segments 
; 64K code; 64K data 
; Reserve space for stack 


Attribute ; Attribute for DirSearch 
FileName ; Offset to file name in DTA 
Cr ; ASCII carriage return 

lf ; ASCII line feed 


DATASEG 


ween 0 
Gr, Gf, “s! 
128 DUP (7?) 


; ASCIIZ (null-ending) string 
; Carriage return, line feed 
; 128-byte unitialized buffer 


; Initialize DS to address 
of data segment 
; Tell DOS to use our 
disk transter area (DTA) 
; Call DOS, assign DTA address 


OFFSET DTA 


OFFSET ListDir 

Attribute 

OFFSET FileSpec 
DirSearch 


; Address ListDir subroutine 
; Assign attribute to cx 

; Address wild card string 

; Search and list directory 


ax,04C00h 7 End with exit code = 0 
21h ; Return to DOS 


i-- Directory Search subroutine 
Input: bx = address of subroutine to call for each match 
cx = attribute(s) to match 
ds:dx = address of ASCIIZ wild card string, e.g. "*.PAS",0 


DirSearch 
ah, 4eh 7 Find-first function number 
short a@t20 ; Jump into loop 


; Find-next function number 


; Call DOS, find first/next 
; Exit when done 

; Call user subroutine 

; Continue searching 


; Return to caller 


List directory entry subroutine 
Input: DTA contains one directory entry from DirSearch 


ListDir 
cld 7; Clear direction flag 
mov si, OFFSET DTA+FileName ; Address file name in DTA 


al<-name[si]; si<-si+1 

Is al = 0? 

If al = 0, jump to exit 
Display-char function number 
Move char to dl 

Call DOS, print character 
Do next character 


ah, 9 
dx, OFFSET Crif 
2th 


Display ASCII$ string 
Assign offset to Crif string 
Call DOS, print string 
Return to caller 


see see 


7 End of text. Program entry point. 
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PROFESSIONAL TOOLS 


PARSING PAL STRINGS 


WITH MATCH 


A reliable tool for parsing string 


Ss 


is needed to split Paradox fields into subfields — 


MATCH fills the bill. 


Bill Cusano 


Sooner or later it’s going to happen: Your 
database needs will eventually grow to the 
point where you need to restructure a ta- 
ble to provide more detail. A 5000-record 
name and address table that contains city, 
state, and zip code information in a single 
field is a perfect example. If you want to restructure 
the table so that city, state, and zip code each have 
their own field, you have a serious problem. 

The solution is a parsing tool that splits the ad- 
dress field into its three components: city, state, and 
zip code. In the grammatical sense, parsing means to 
split a sentence into its grammatical components 
(i.e., subject, verb, object, and so forth). What’s 
needed here is a variation on that theme—a method 
of splitting a string along some logical boundary, 
such as a comma, a space, or some other combina- 
tion of characters. 


PROGRAMMER 


THREE ON A MATCH 


A PAL function, called MATCH, provides a way to 
match a string against a pattern. The syntax of 
MATCH is: 


MATCH(String, Pattern, [Vars] ) 


String is the text string to be tested, Pattern is a 
string template against which the string is matched, 
and [Vars] is an optional list of variables used in seg- 
menting the string on the first occurrence of a pat- 
tern match. To see how this type of parsing can help 
solve our problem, let’s look at a few typical strings 
that contain city, state, and zip code data: 

"Scotts Valley, CA 95066" 

"Los Angeles, CA 90066" 

"Redmond, WA 98073" 

"East Hartford, CT 06108" 

The four lines shown above contain similar logical 
boundaries between the separate data elements that 
are to be extracted. All of the lines contain at least a 
comma between the city and state information, and 
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at least one space between the state and zip code in- 
formation. This pattern is consistent through all of 
the strings. 

Defined concisely, the pattern consists of a vari- 
able number of characters for the city, followed by a 
comma and one or more spaces, followed by two or 
more characters that represent the state, and ending 
with one or more spaces followed by the zip code. 

In PAL, the double period (..) in a pattern string 
represents any number of alpha, numeric, or special 
characters. The double period can be used to build 
the pattern just described. The first part of the pat- 
tern string contains a double period to represent the 
variable number of characters (including spaces) 
that comprise the city information. This double pe- 
riod is then followed by a comma and a space (.., ) to 
indicate the logical break between the city and the 
state. 

Another double period followed by a space (.. ) 
represents the pattern for the state information and 
its separator from the zip code. Although each state 
is represented by only two characters, we can’t be 
sure how many spaces will precede the state infor- 
mation, so the double period is used just to be safe. 

A final double period represents the zip code and 
the complete pattern string becomes “.., .. ..”. A vari- 
able name must be present to receive each segment 
of the information (i.e., each portion represented by 
a double period); the variable names City, State, and 
Zip are used in this example. A MATCH function 
can then be stated for each of the example strings, 
as shown in Figure 1. 

Tidy as they seem, these MATCH invocations 
won't do the job in all cases. In all except the first ex- 
ample string, in fact, the value of the variable State 
is set to a single space character because multiple 
spaces are present between the comma and the state 
code. In such a case, the middle double period (..) in 
the match pattern picks up the second blank space 
after the comma and considers that blank space to 
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INTRODUCING 


Version 
| 


from Zenreich Systems 


In Paradox, you create many tables and often quite a bit of confusion. 
How many times have you asked yourself: 


@ | have many tables in several directories, how can | keep track of them? 
e Are my Field Types, Image Formats and Validity Checks consistent across my tables? 
@ | renamed my “Staff” table to “Employee”, where do | have to make Tablelookup changes? 
@ How much disk space is used by a table and its entire family? 
@ What settings have | placed in reports (length. width, setup, etc. )? 
@ How can | tell when my tables need to be restructured to remove wasted space? 

@ Which of my tables are encrypted, write protected, or corrupted? 

@ What rights have | assigned to each field for password protected tables? 


The 12 ParaLex reports answer all of these questions, and many more. ParaLex creates Data, Table and Password 
dictionaries that gather extensive information from your Paradox tables. 

The reports may be sent to printer. screen, or disk file. Dictionaries are Paradox tables, so you have total flexibility. 
ParaLex is menu driven, so it’s easy to use. We can't imagine Paradox applications without ParaLex. 


Although ParaLex list price is $149.95, 
you may order for only $99.95 + $5.00 shipping and handling. 


You may order by credit card, by calling 800-336-6644. Checks and Purchase orders may be sent directly to: 


Zenreich Systems 
78 Fifth Avenue, New York, NY 10011. = 212-691-0170 
ParaLex requires Paradox 2.0 (or higher) and a 640kb machine 
ParaLex is written is proceduralized PAL code. Registered ParaLex users will receive a disk with several useful procedures that went into the building of ParaLex 


ParaLex was reviewed by the Paradox Users Journal, and DataBased Advisor 


Enhance the power of Paradox. 


With PlayRight. The first ASCII text editor designed especially for Paradox. PlayRight’s multi-file editing, 
extensive block operation, script formatting, custom configuration and spool-printing capabilities bring speed 
and efficiency to your writing—and debugging. And, because it looks and feels like your built-in PAL editor, 
it’s easy to use. PlayRight snaps right into Paradox, instantly replacing the simple PAL editor. Instantly 
enhancing the power of Paradox. 
Compatible with Paradox 2.0 and 386. 

“PlayRight is great—I can hardly imagine anyone 
who writes scripts being without this program.” 

—Doug Cobb 


Paradox Users Journal The Paradox™ Script Editor 
October 1987 


$129.95 30-day money back guarantee 
To place your credit card order: 
800-262-8069 

For a free brochure, call 

704-552-9875 


The Burgiss Group 3332 Eastburn Road Charlotte North Carolina 28210 


Paradox is a registered trademark of Ansa Software; Ansa is a Borland International Company. 


LISTING 1: CSZ.SC 


Csz.sc 
Bill Cusano (516) 293-6846 


3 SCRIPT: 
7 AUTHOR: 


; FUNCTION: Demonstrate using MATCH to parse a string 


PROC CSZSplit(CSZ) 
PRIVATE x4,x5 


The IF statement below tests whether the string in CSZ 
matches a given pattern. The MATCH function performs 
this test, and if the test passes, variables City and 
State are assigned the values of their corresponding 
patterns within the string. The double dot (..) pattern 
used here accepts any number of characters or numbers in 
the position. 


IF MATCH(CSZ,".., ..",City,State) THEN 


The WHILE command below tests, in each pass through 
the loop, that the string value of the variable State 
matches the quoted pattern. Here, if the string 
contains a leading space, the loop continues. The 
MATCH function performs @ logical test for a match 
and, upon a match, it fills the variable x4 with all 
characters to the right of the leading space. 


WHILE MATCH(State," ..",x4) 


Each pass through the loop causes the variable 
State to be reassigned to the value of x4. Thus 
the string loses its leading blank space. 


State = x4 
ENDWHILE 


The WHILE loop above would only be run if there 
are leading spaces in the string. If it does 
not run, we need to assign the value of State to 
the variable x4, which is tested below. 


x4 = State 


Here, we're using MATCH again to separate out the 
State and ZIP data from the remains of the string 
once City has been removed. 

IF MATCH(x4,".. ..",State,Zip) THEN 

This WHILE statement removes leading spaces from 
Zip: 


WHILE MATCH(Zip," ..",x5) 
Zip = x5 


ENDWHILE 
ENDIF 
ENDIF 
ENDPROC 


; Below is a test program for procedure CSZSplit: 


City =" 
State =" 
Zip=™ 


@ 2,4 2 "Enter String: " 
ACCEPT "A25" TO CSZ 
CszSplit(csz) ; Split city, state, and ZIP from CSZ 


; Enter e string to split 


@ 6,4 22 City 
@ 7,4 22 State 
@ 8,4 2? Zip 
sleep 3000 


3 Show the three fields split from string CSZ 
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PARSING STRINGS 
continued from page 126 


MATCH 
("Scotts Valley, CA 95066",".., .. ..",City,State,Zip) 
MATCH 

("Los Angeles, 
MATCH 
("Redmond, 
MATCH 
("East Hartford, 


CA 90066",".., .. .." City,State, Zip) 
WA 98073",".., .. ..",City,State,Zip) 
CT C6108 t ML, cn on! City, state, zip) 


Figure 1. A first cut at using MATCH to parse city, state, 
and zip information from a single string. This won't work 
correctly because there may be multiple spaces between the 
components, and there’s no way to match on multiple 
Spaces. 


be the state information. The Zip variable then con- 
tains all of the remaining information in the string, 
which includes both the state and zip code. 

To allow for extra spaces, the string must be split 
into two stages. In the first stage, the string is split 
into two pieces, rather than three. As a result of the 
following MATCH statement, the variable City con- 
tains the city information, and the variable State con- 
tains both the state and the zip code: 


MATCH("Redmond, WA 98073",".. ..",City,State) 


Any leading spaces in the string in State can be 
trimmed by using another MATCH statement within 
a simple loop test, as shown in Listing 1. 

Once the city data has been parsed out, the same 
process is repeated in order to split the State string 
that now contains the state and zip code information. 
After copying State into a temporary variable named 
x4, the following invocation of MATCH performs the 
second split: 


MATCH(x4,".. ..",State,Zip) 


Again, a WHILE loop should be used after the split 
to remove any leading space characters from the Zip 
string. 


LET’S SPLIT 


The CSZSplit procedure in Listing 1 demonstrates the 
versatility of the MATCH function in parsing the ad- 
dress string to produce separate city, state, and zip 
code strings. Once you add three new fields to the 
original table to house these values, you can loop 
through the expanded table record by record and 
store the values of the variables City, State, and Zip 
into the new fields. PAL can do it—problem 

solved! @ 


Bill Cusano is the owner of Cusano Marketing, a consult- 
ing group that offers training and developer support mar- 
keted under the name “Sable Solutions.” 


Listings may be downloaded from Library 1 of CompuServe 
forum BORAPP, as PMATCH.ARC. 


CAPTURING DIRECTORIES 
WITH SPRINT 


Sprint’s gateway to DOS—the call command — 
lets you consider much of DOS’s power 
as an extension of Sprint. 


PROFESSIONAL TOOLS 


Bruce F. Webster 


Quite apart from the expected text-pro- 
cessing features, Sprint’s macro language 


LISTING 1: DIR.SPM 


offers considerable low-level access to : 
DOS and to the computer itself. This is ; GetDirectory: 
: ony : asks for file specification, gets directory listing (redirected 
ee exemplified by Sprint s call command, s into temp file), reads listing into file being edited, deletes 
PROGRAMMER which lets you execute DOS commands or | | i _ tew file 
external programs through DOS’s Exec function. In GetDirectory: ; name of macro 
; : ’ C : set QF "DIR.LST" 7 set name of temp file 
this article, rl present GetDirectory, a Sprint macro message "Enter filespec: " set Q0 ; get file specification 
that illustrates how a technical documentation spe- eos = - awe past iswhite } ; delete leading balnks 
oe f i Q 3 if fil tered 
cialist might take advantage of these features to cus- ; saeaaee mteicitg ee wee ink eeosens 
tomize Sprint for special needs—in this case, to eas- ee ie mee ae Sete ae tile 
ily input a file directory summary without leaving status "\nReading in results..." ; print message 
. . 32 call “command /cERASE " QF 7; ERASE temp file 
Sprint. GetDirectory uses call to execute a DOS DIR 5 Ste ds sachin 


<filespec> command, redirect DOS’s output to a 
disk file, and then read the disk file into a document 
at the cursor position. 


DISSECTING A MACRO 


The Sprint source code for GetDirectory is given in 
Listing 1. Because of the terseness of the Sprint 
macro language—which resembles a cross between 
Forth and C—GetDirectory isn’t very big. Let’s dis- 
sect it, line by line, to see just how it works. 

The first line of code establishes the macro’s name 
(GetDirectory). Macro names are not case-sensi- 
tive—GetDirectory and getdirectory are seen as the 
same by the macro compiler. When beginning a new 
macro, you must specify the macro name, followed 
by a colon. This signals the end of the previous 
macro (if any) and the start of the new macro. 

The command set QF “DIR.LST” on the next line 
copies the string “DIR.LST” into the variable QF. 
OF is one of Sprint’s 26 predefined string variables, 
which are named Q0..Q9 and QA..QP. DIR.LST is 
the name of the temporary disk file that will hold the 
directory listing. 

A file specification for the directory listing is en- 
tered via the following line: 


message “Enter filespec: " set Q0 


This is a standard method for printing a prompting 
message on the status line and then reading in a re- 
sponse from the keyboard. In this case, the response 
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DIRECTORY CAPTURE 
continued from page 129 


is copied into variable QO. In general terms, the 
command message <string> prints <string> on 
the status line. The command set Q<n> may take 
an optional string value (as shown earlier). When 
the string value is present in a set command, the 
value is copied into the named variable. Since no 
string value is contained in the set command in Get- 
Directory, set waits for string input from the key- 
board. The string data read from the keyboard is 
then assigned to Q<n>. 

The mark command in the next line is somewhat 
tricky. The syntax mark {...} saves your place in the 
edit buffer, executes the commands within the curly 
braces, and then returns you to your position in the 
edit buffer. The command to Q0 states that you are 
now editing the contents of Q0. The command 
string delete past iswhite deletes any leading white- 
space (blanks, tabs, and so forth) in QO. The aim is 
to remove any leading blanks that you might have 
entered in the file specification. 

The rest of GetDirectory is contained in a single 
if statement. Sprint’s if statement general format is: 


if <expression> <command> 


Since each separate Sprint macro command can be 
considered an expression, combinations of com- 
mands that act as one expression must be enclosed 
in parentheses. Likewise, in order for the if state- 
ment to execute more than one command, the com- 
mands to be executed must be within curly braces. 

The expression (0 subchar QO) tests to see 
whether or not Q0 contains a file specification. The 
literal effect of (0 subchar QO) is to return the char- 
acter stored in QO[0]. If QO is nonempty, then the re- 
turned character is nonzero, which is equivalent to 
TRUE. If the expression resolves to TRUE, then the 
rest of the if statement is executed. If QO is empty, 
then the returned character is NULL (ASCII 0, the 
standard C end-of-string character), which is equiva- 
lent to FALSE—this means that the rest of the if 
statement is then skipped. 

The first line of the if statement’s block calls mes- 
sage twice. The first invocation of message clears the 
message bar (by virtue of the leading \n, which 
prints a new line) and displays the string “Looking 
for.” The second invocation of message prints the 
file specification contained in QO. The two displays 
comprise a status message that’s shown to the user 
while the directory is being read. 

The next line contains the DOS Exec command 
call. The number (32) that precedes call is a com- 
mand code that tells call not to switch to the DOS 
screen; as a result, the DOS operation happens invis- 
ibly. All of the strings that follow the call keyword are 
concatenated together and then passed to DOS 
through the Exec function. In this case, COM- 
MAND.COM is executed by using the /c directive to 
pass a command line to COMMAND.COM that con- 
sists of three items: “DIR,” the file spec in QO, and 
the redirection command “>DIR.LST.” In effect, the 
following DOS command is being executed from 
within Sprint: 
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DIR <filespec> > DIR.LST 


The output from the DIR listing is redirected to the 
file DIR.LST. 

Once created, DIR.LST must be read into the file 
that you're editing, by the read QF command. QF, if 
you remember, contains the string “DIR.LST,” 
which is the name of the file that contains the direc- 
tory data. The read QF command automatically dis- 
plays the message “Reading in DIR.LST...” and starts 
the reading process. 

The status command on the next line is very 
much like the message command, except that status’s 
message is automatically erased as soon as another 
status or message command is executed. The status 
command is actually executed before Sprint finishes 
reading DIR.LST, so that status’s message replaces 
the message displayed by the read command. 

The macro’s last line uses the call command to 
execute COMMAND.COM again. This time, COM- 
MAND.COM is passed the command string “ERASE 
DIR.LST,” which deletes the temporary file DIR.LST 
once DIR.LST is no longer needed. 


FETCHING A DIRECTORY 


To use GetDirectory, run Sprint, key in the source 
code, and save the source code as DIR.SPM in your 
Sprint directory. Close that file and open a document 
file. Bring up the Utilities menu by pressing Alt-U. 
Select the Macros submenu and then choose the 
Load command. You'll be shown a list of all of the 
.SPM files in your Sprint directory; select DIR.SPM 
and press Enter. You’ve now loaded the macro and 
compiled it into Sprint. 

To use the macro, select the Utilities/ Macros/ 
Enter command. When the status line prompts you 
for the macro name, enter GetDirectory. Sprint then 
asks if you wish to Execute the macro or to Assign 
the macro to a key sequence. Press “A” (for Assign), 
then press Alt-H to assign the macro to the Alt-H 
hotkey. (I present Alt-H as an example because it 
isn’t used by the standard Sprint interface.) 

Now, move the cursor to some point in your file 
and press Alt-H. When the status line prompts you 
for a file specification, type “*.*” and press Enter. 
The message “Looking for *.*” appears on the status 
line, followed by the message “Reading in results...”. 
The standard directory information for the specified 
files is then inserted at that point in your file. 


THE call OF THE WILD 


The techniques embodied in GetDirectory can eas- 
ily be adapted to other purposes. For example, you 
could reproduce the Utilities/DOS command func- 
tion for use within a custom user interface. The call 
command could be set up to run another program 
instead of COMMAND.COM. call is your gateway to 
DOS—let your imagination go to work. & 


Bruce Webster is a computer mercenary living in Califor- 
nia. He can be reached via MCI MAIL (as Bruce Webster) 
or on BIX (as bwebster). 


Listings may be downloaded from Library 1 of the 
BORAPP forum on CompuServe, as SPDIR.ARC. 
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SPECIAL OFFER: 
ONLY $99.95! 


The race into the Age of 
Customization is on—led by 
Sprint.” You can use Sprint as 
is and be very happy with the 
way everything works for you 
—or you can easily customize 
Sprint to do everything 

your way. 

It’s a completely 
customizable word processor 
that, for example, lets you 
re-define keys, delete menu 
items, make your own short- 
cuts, invent your own menus, 
and use Sprint’s online facil- 
ity to create your own quick 
reference cards. 


*Customer satisfaction is our main concern; if within 60 days of purchase this 
product does not perform in accordance with our claims, call our customer 
service department, and we will arrange a refund. 


All Borland products are trademarks or registered trademarks of Borland 
International, Inc. Other brand and product names are trademarks of their 
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Why walk when 


You're given the 
customizing power to avoid 
pop-up menus altogether— 
if that’s the way you like to 
work. Sprint can be com- 
pletely function-key-driven, 
and while Sprint’s function 
key assignments are logically 
defined, they're easy to alter. 


Nothing goes slow 
when you Sprint! 


Sprint is fast. It scrolls fast, 


edits fast, switches between 
files fast, offers fast shortcuts 
and proves that the slow way 
is nO way. 


Prices and specifications subject to change without notice. 


Minimum System Requirements: 


For the IBM PS/2 and the IBM family of personal computers and all 100% 
compatibles. Requires PC-DOS (MS-DOS®) 2.0 or later, 256K memory (384K 
recommended), and two floppy drives or a hard disk. 


You can work on up to 
24 files at once, divide 
your screen into as many 
as Six windows, and never 

miss a beat because Sprint 
remembers which files 
you were working 

on last. 

Because Sprint brings 
you the speed you’re 
used to with Turbo 
Pascal® and Turbo C° 
it never wastes your 

time and true Turbo- 
performance is finally 
available in a text 
editor. 

To see just how 
much faster Sprint works for 
you, check out the compara- 
tive time tests. 


Sprint gives you six 
optional interfaces 
including EMACS 


The customizing you 
choose to do is one variation 
on Sprint's theme and there 
are six others. 

We give you free (for a 
limited time) Alternative 
User Interfaces for: 


¢ EMACS ¢ WordPerfect® 

¢ WordStar® ¢ MultiMate® 

¢ Microsoft® © SideKick® 
Word 


And you also get file 
conversions for: 


¢ WordStar 
Microsoft Word 
WordPerfect 
MultiMate 
DisplayWrite® 4 
(DCA RFT) 


you can Sprint? 


Sprint lets you use EGA See how fast you can Sprint! 
and VGA cards for 48- or 
50-line displays; it directly Save File! | 10P to, Go To Line Search & Find | 
reads ASCII files without Bottom 1500 Replace® | Unique Word 
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compiler with a syntax similar 


to C; separate source files; an Tests were performed on a Multitech 286 AT (8 MHz), 640K RAM. ‘file size 103K. °1636 lines. 
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fact of life as are power out- 
ages, and it used to be that 
a power outage could wipe 


Stonewall Times 


a sMYTHE q The Employee ese of _coeewet Brokers, Inc. 
222 Fountain 35005 7 
Lomont, 3 We'll Be Havin’ Parking Probl 
8 (408) 555-5559 - Sonne Fair ing Employees of the 


As you can see by th nical 
Th i sit He 
ba Fesged “a tee ena ner 93 little Congratulations to the fol- 
suet yea ‘open : aa ve sg ? so little lowing Stonewall employees: 


walk, on Friday, June 10th, 3 Annette Christensen and 


It will start at high noon. eruonne! Requrermones Brad Dix for setting up the 
We will have two volleyball Stonewall Brokers, Ine new computer system; 
oa loads of beach os 4 Dennis Feldman for refer- 
Ma wet hid ror boi sans el 1 ring a new large client; 
; ev F 
7 Customer Servic Shc INC i Weill end with a bonfire end | ay wipe ita olla 
4 November 198 RES! ‘fornia ae correspondent marshmallows, io SEE OMI, 
1 to Scotts Valley, Pe : handling, pro. ee Perl er 3 sel 4 Bradley Hughes and 
Present Responsible, Or npany. Responsy: written and ¥ We'll be barbecueing beef rib “ nin etonniey ltt 
“ CRO of compomers, as well rc uct orders steaks, chicken thighs ¢ por anles colete: 
in Cl . \vin} t te 1 iJ roms 108s t00n 198? 1908 ments; and 
West Get mers, il i anagement T salmon steaks, and vege- Ve 7 
ith U.S: custon working with kr at Bompan y table kabobs. Since we Until oem Stanley for 
blem Solving reports * ds} can't provide all f enrceatiet A nce peoimanieng te, 
pro databases 4 ackages am sp i Provide all four to structure is finished, we're warehouse 
sawed ge of accounting P paras be ane e sign going to continue having : 
a ; y Planning for arkin, f 
+ onist/Office Manage® j your choice of food before ae if ance Ee. 
October 1986 RecehOR SERV ICES, INC- ointt kad ve Mids a ie Please do so (il you want” Promotio 
storni , a s » Dreads, vegetables, 
to ber 1987 Santa C Aeeey included, daily Re an baked potatoes, on ory peo posed salt as 
November * Respone. on pr ction | charges and Pe serts, as well as three or sonnel). Whatever you do. The President's Office is 
emphasis ccounts receivan et end contre four dozen different items don't take up two spaces for picsped anit proud to 
Penk Keposits, sate o rranwal system to an for your snacking pleasure. any reason. The visitor announce the following 
7 ro! 3 parking area promotions; 
oT space le Clerk } i ich apie gst ‘only; (That's yon 4 Robert Schindler h 
ivable C NY 3 much fun as you did last 1" : ‘ ge aba 
ot 1985 Accouny Latin LUMBER COMPA year, but we've decided Ser ee Mae named Assistant 
Augus HA California hin against serving and allows Be Cerca MoE 
to 4936 Santa Cr ities included, sete rg at alcoholic beverages. Sg Hip atin, Sn nerupreg Me a Betty Willards will 
October aca aan reconciled, mtorr inquirie don't bring any, It will ecrse sb gs Ch st cobain ang 
com ’ hand repare ecount Representative, 
jnvole ash receipts ae P ‘ormet Just like last year, parking for 60 cars and a Joy Flannery will be the 
ed daily ca ator and = year, everyone uncovered parking for ty 
poate! | {the EDP opera 4 will get a Stonewall Towel, another 60. Since covered lagi oh a 
ssisted 2 : anager, 
‘as required. nigh ee, = bb including parking will be in such ais 
= AE ON: demand, we're going to 
jonis! d 
April 1981 Recs PrT-CARE OFFICE ; Hf you want to help plan the petiateapal ae See 
P H Califorme daily appo! party, come on down and : W-4 Form 


se, ea d, A 
t0 agar = Gan JOSE: Ee. included, CF? and. dive us your ideas. We need 


You have a head start when you Sprint! 


Sprint WordPerfect MS Word WordStar MultiMate Adv. 
1.0 4.2 4.0 4.0 II, 1.0 

Maximum file size Disk Disk Disk Disk 128K 
Mail Merge Yes Yes Yes Yes Yes 
Thesaurus (integrated) Yes Yes Yes Yes Yes 
Windows Open (maximum) 6 2 8 1 1 
Files Open (maximum) 24 2 8 1 1 
Cross-Reference (dynamic) Yes No No No No 
Indexing Options 7 1 3 3 No 
Snaking Columns (chg * on same Yes Yes Not same pg. No Yes 
page) 
Parallel Columns Yes Yes Yes Yes Yes 
H-P LaserJet Support Full Full Full Partial Full 
PostScript Support Full Text Full No Text 
Mouse Support (integrated) Yes No Yes No No 
AutoSave (without interruption) Yes No No No No 
User Interface 
Define Shortcuts Dynamically Yes No No No No 
Run Alternative User Interface Yes No No No No 
Verify spelling as you type Yes No No No No 
Fully programmable macro language Yes No No No No 
Suggested List Price $199.95 $495.00 $450.00 $495.00 $565.00 


What you get when you Sprint! 


SideKick, WordStar, Word- 
Perfect, Microsoft Word, 
and MultiMate 


Comes with an integrated 
100,000-word speller and 
220,000-word thesaurus 


Produces highly profes- 
sional output: long or short 
documents, cross-refer- 


¢ Includes Auto-Save that 
saves your work without 
interrupting it 

Sprint supports 350 popu- 
lar printers including 

HP LaserJet,® other laser 
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Bruce F. Webster 


ast issue, I talked about a number of the 

basic data types and structures, and how to 

design them. In this issue, I’ll explore an- 

other category of data types and will discuss 
some guidelines for data structure design. 


ENUMERATED TYPES 


An enumerated data type (or EDT) is a user-defined 
data type. In defining an EDT, you list (or enumerate) 
its possible values, which are identifiers enclosed 
within parentheses and separated by commas. Any 
of the enumerated values can then be assigned to 
variables that are declared to be of that data type. 
Figure 1 gives examples of a few EDTs in both Pascal 
and C, and shows how you might use them. 

Enumerated data types are actually disguised inte- 
ger constants. In Pascal, they’re strongly disguised— 
you can’t use these integer constants directly in inte- 
ger expressions unless they’re converted first into an 
integer value via the Ord transfer function. In C, you 
can treat enumerated data types exactly like int 
values. In both languages, the first identifier has a 
default value of 0, the next has a value of 1, and so 
on. Thus, N identifiers map onto the integer range 
0..N-1. As shown in Figure 1, C gives you the addi- 
tional ability to explicitly assign values to given iden- 
tifiers. In fact, since EDTs in C are really just inte- 
gers, most of the following discussion focuses on 
EDTs in Pascal. 

What issues are involved in the design of enumer- 
ated data types? The first issue is this: Why use enu- 
merated data types at all? Answer: To help document 
your program. When used properly, EDTs make your 
programs easier to read and modify. Compare the 
code shown in Figure 1 with that in Figure 2, which 
shows the Pascal code from Figure | with all EDT 
values converted to their corresponding integer 
values. It is not at all clear from the code what the 
values 9, 1, 5, and 3 represent; in fact, the first value 
is misleading, while the last value bears no apparent 
relation to what it represents. 

This brings up the second issue in EDT design: 
mapping. As defined in Figure 1, the values January 
through December in the EDT Months correspond 
to the integers 0..11. However, you may want these 
values to correspond to the integers 1..12 for calcu- 
lation or other purposes. To implement this change 
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BINARY ENGINEERING 
Designing data structures, part II 


LISTING 1: TESTDAYS.PAS 


program TestDays; 
uses CRT; { for ClrScr, GoToxY, Clreol > 


type 


Days = (Sun, Mon, Tues, Wed, Thurs, Fri, Sat, endDay); 


const 


DayName : array[Days] of string[5) 


= ('Sun', 'Mon', 'Tues', 'Wed', 'Thurs', 'Fri','Sat',''); 


var 
Today, Tomorrow : Days; 


function ToUpper(S : string) : string; 


z= 1 to Len do begin 
Ch := SII); 
if ('a' <= Ch) and (Ch <= 'z') 
then S{I] := Chr(Ord(Ch)-32) 


ToUpper 22 $ 
end; { of func ToUpper } 


function GetDay(Prompt : 
€ 


string) : Days; 


writes out Prompt at (1,1) -- continues to prompt until 
the user enters a valid day name (Sun..Sat); case doesn't 


matter -- returns the day value entered 


var 
Ans : string(5); 
Day : Days; 


begin 
repeat 
GoToXY(1,1); ClrEol; 
Write(Prompt); 
Read|n(Ans); 
Ans := ToUpper(Ans); 
Day := Sun; 


while (Day <= Sat) and (Ans <> ToUpper(DayName [Day] )) do 


Day := Succ(Day) 
until Day <> endDay; 
GetDay := Day 

end; { of func GetDay > 


begin { main body > 
ClrSer; 


Today := GetDay('Which day of the week is today? '); 


Tomorrow := Succ(Today); 
if Tomorrow = endDay 
then Tomorrow := Sun; 
Writeln('Tomorrow is : 
end. { of program TestDays } 


* ,DayName [Tomorrow] ) 


Turbo Pascal: 


type 
Days = (Sun, Mon, Tues, Wed, 
Thurs, Fri, Sat); 
Months = (January, February, March, 


April, May, June, July, 
August, September, October, 
November, December); 

Coins = (penny, nickel, dime, quarter, 
halfdollar, dollar); 


var 


Today : Days; 
ThisMonth : Months; 
Coin : Coins; 
begin 
ThisMonth := October; 
for Today := Mon to Fri do begin 
end; 
Coin := quarter; 
end. 
Turbo C: 


typedef enum { sun, mon, tues, wed, 
thurs, fri, sat } days; 

typedef enum { january, february, march, 
april, may, june, july, 
august, september, october, 
november, december } months; 

typedef enum { penny=1, nickel=5, dime=10, 
quarter=25, halfdollar=50, 
dollar=100 } coins; 


main { 
days today; 
months thisMonth; 
coins coin; 
thisMonth = october; 


for(today = mon; today <= fri; today++) ¢ 
2 
coin = quarter; 


in Pascal, you must actually expand 
the EDT definition and give it a 
new dummy initial value to map 
to 0. In C, another solution is 
available: Just assign the value of 
1 to the identifier january and the 
other months will follow suit, so 
that february will have a value of 
2, and so on. Figure 3 shows ex- 
amples for both languages. 

Note that the noMonth solution 
in Figure 3 has another advan- 
tage: It can act as a “null” value. 
When assigned to a variable, a 
null value indicates that the vari- 
able doesn’t currently hold any 
particular month. This allows you 
to distinguish between variables 
that have actually been assigned 
a given value, and those which 
aren't currently being used. 

Another reason why you might 
want to “pad” the beginning or 
the end of an enumerated type 
with extra values (especially in 
Pascal) is range checking. Con- 
sider the code in Figure 4, which 
sets up a while..do loop to cycle 
through the days of the week, and 
increments Day at the end of the 
loop. The problem is this: If 
range checking is enabled and 
Day = Sat, then the statement 
Day := Succ(Day) causes a run- 
time error. Why? Because the vari- 
able Day is only allowed to have 
the values Sun through Sat. Thus, 
Succ(Sat) is out of the range of the 
EDT, and therefore is undefined. 
One solution, shown in Figure 5, 


} is to pad the EDT with an extra 
value at the end so that Day holds 
Figure 1. Some examples of enumerated data types and how they are used. the value endDay after the last call 
to Succ. (Another solution, of 
course, is to turn off range check- 
var 


Today, ThisMonth,Coins : integer; 


ing, but that decision may return 
to haunt you later.) 


begin There’s one last problem with 
ThisMonth := 9; EDTs: text I/O. Pascal doesn’t 
for Today := 1 to 5 do begin support the reading of EDT values 
ie directly into an EDT variable, nor 
Poth ow 5 does it allow an EDT value to be 
iets ‘ put into a Write or Writeln state- 
end. ment. Your only real option with 
Pascal is to typecast the EDT value 
Figure 2. The Pascal code from Figure 1, with all EDT values converted to to some type (such as Char or In- 


their corresponding integer values. 


teger) that’s compatible with text 
I/O. C does let you treat enum 
variables just like any other inte- 
ger variable, but (as with typecast- 
ing EDT values in Pascal) that 
doesn’t help you if you want to en- 
ter or display an actual EDT value, 
such as january or penny. 
continued on page 138 
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Turbo Pascal: 


type 


Months = (noMonth, January, February, 


March, April, May, June, 
July, August, September, 


October, November, December); 


Turbo C: 


typedef enum { noMonth, january, february, 
march, april, may, june, 
july, august, september, 


october, november, 
december } months; 


or 


typedef enum { january=1, february, march, 
april, may, june, july, 
august, september, october, 
november, december } months; 


Figure 3. Pascal and C adjustments to make an enumerated type line up with 


a given range of integers. 


type 


Days = (Sun, Mon, Tues, Wed, Thurs, Fri, Sat); 


var 
Day : Days; 


begin 
Day := Sun; 
while Day <= Sat do begin 


Day := Succ(Day) 
end; 


end. 


Figure 4. Code that generates a runtime error if range checking is enabled. 


type 
Days = (Sun, Mon, Tues, Wed, 


Thurs, Fri, Sat, endDay); 


Figure 5. One solution to the problem in Figure 4. 


BINARY ENGINEERING 


continued from page 137 


The general solution here is to 
construct an array of strings that 
contain text equivalents of the 
EDT values, and then index the 
array by the enumerated type. For 
input, read in a string from the 
console, compare that string to 
each of the strings in the array, 
and use the corresponding EDT 
value when a matching string is 
found. To make the process case- 
insensitive, convert both strings to 
upper- or lowercase before the 
comparison. Similarly, the same 
array can be used to display or 
print the string that represents 
each EDT value as needed. I’ve 
provided the Pascal implementa- 


tion of this solution in Listing 1; 
the C implementation is (as they 
say) left as an exercise for the 
reader. 


OUTPUT AND INPUT 


In this and my previous columns, 
I’ve talked a fair amount about 
some of the different data types 
and structures that you can have 
in a program. The question still 
remains: How do you go about de- 
signing them? The first step is to 
look at the output that your pro- 
gram requires. The ultimate pur- 
pose of a program is to produce 
output of some sort: text, data, 
graphics, electronic signals to 
hardware, or (in the case of many 
benchmarks) duration of execu- 
tion. The information that a pro- 
gram generates determines what 
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information it must track during 
execution—and the latter is the 
information that goes into your 
data structures. 

Anticipated input also affects 
the design of your data structures, 
since you need some way to hold 
whatever data the program might 
receive during execution, whether 
that be from a file, from the user, 
or from some other device. The 
input itself is ultimately deter- 
mined by the nature of the de- 
sired output. 


CALCULATION VERSUS 
STORAGE 


Just because your program outputs 
certain information doesn’t mean 
that your data structures must 
hold that information. For exam- 
ple, a program that prints a mul- 
tiplication table doesn’t need to 
hold the entire table in an array. 
Instead, the program can generate 
a value in the table and then print 
the value, based upon a few pieces 
of information. Likewise, a pro- 
gram that draws a circle on the 
screen only needs to know the cir- 
cle’s center coordinates, its radius, 
the line width, and the line color; 
the program doesn’t have to keep 
an actual copy of the screen 
image. 

The same principle holds true 
for the internal workings of the 
program. Suppose you write a 
spreadsheet program where each 
cell is represented by a record. 
You could choose to implement 
the spreadsheet as a linked list of 
those records, traversing the list to 
find the cells as you need them. 
With this method, records are 
created only for the nonempty 
cells. While this minimizes mem- 
ory usage, it does so at the cost of 
performance. As an alternative ap- 
proach, you could implement the 
spreadsheet as a two-dimensional 
array of the same records. In this 
case, you can access any cell di- 
rectly, and perform operations on 
the spreadsheet very quickly. Re- 
gardless of how small the actual 
spreadsheet is, however, a large 
amount of memory is used with 
this method, and the size of the 
spreadsheet is quickly limited. 

The above example represents 
a classic tradeoff in computer pro- 
gramming: speed versus memory. 


You can often make a program 
run faster if more explicit infor- 
mation is stored, but to do so re- 
quires additional memory. Like- 
wise, less memory is used if the 
minimal information is stored and 
the rest of the information is cal- 
culated as needed; however, the 
program will run more slowly. 

Which way should you go? That 
depends, of course, upon which 
resource is more limited: time or 
space. If you’re trying to make the 
program run as fast as possible, 
then you can use memory to hold 
more explicit information. For ex- 
ample, I once wrote a graphics 
package that drew certain geomet- 
ric figures by calling a few trig 
functions (sin and cosine). Unfor- 
tunately, that process slowed 
things down. My solution was to 
create an array to hold all of the 
required values, and then to index 
into that array to get the values. 
The result was a significant im- 
provement in drawing speed, at 
the cost of the memory that was 
used to hold the array. 

On the other hand, if memory 
is limited, then you can afford to 
take the necessary time to calcu- 
late information as it’s needed, 
rather than to calculate the infor- 
mation once and then store it. For 
example, if an application re- 
quires your program to check if a 
number is prime, standard numer- 
ical checks can be used to deter- 
mine “prime-ness,” rather than 
using the method of storing a 
table of prime numbers. 


GUIDELINES 


What are the criteria to use when 
deciding which information will 
be stored and which will be calcu- 
lated? Here are a few: 


How often do you need this infor- 
mation? If it’s used at only one or 
two spots in the program, you may 
be better off just calculating the 
information at those spots. On the 
other hand, if the information is 
used repeatedly—either within a 
loop or in many different places 
in the program—store the infor- 
mation in memory so that it can 
be quickly retrieved. 


How much space does the infor- 
mation use in relation to other 
data? If you’re writing a payroll 
program, the paycheck amount 
can be calculated as needed and 


may not need to be stored. But in 
this case, you’re only looking at a 
few extra bytes per record, so 

why not just store the paycheck 
amount? It may come in handy 
elsewhere. On the other hand, 
storing an entire multiplication 
table takes up far more space than 
the upper and lower limits that 
are needed to generate it. 


How much time does it take to 
calculate the information? The 
geometric graphics package men- 
tioned above was written for the 
Apple II, which has a fairly com- 
plex relationship between mem- 
ory locations and pixels on the 
screen. My program could make 
the necessary calculations to gen- 
erate the correct byte and bit mask 
values that turn a given pixel on 
or off. However, this process 
slowed things down too much. My 
solution was to set aside several 
hundred bytes of memory for two 
lookup tables that gave me the 
byte-and-bit information for every 
X,Y pixel location on the screen. 


Do you really need the informa- 
tion? It’s easy to get into the habit 
of adding more fields to a record 
than you really need. When writ- 
ing a payroll program, for exam- 
ple, you might be tempted to put 
a lot of extraneous information 
into each record (date of birth, 
sex, height, weight). Such informa- 
tion normally has no bearing on 
the determination of how much 
the person gets paid, so why store 
it? Remember: If it doesn’t affect 
output, then you probably don’t 
need it. 


Do you need to access “subsec- 
tions” of the information? If you 
write a program that prints a list 
of numbers in a series, then your 
best bet may be to simply generate 
the numbers as they are printed. 
However, if you need to reference 
specific numbers in that series, 
then storing the series in an array 
may be the better answer. 


How much storage space do you 
have to spare? If you’ve got a lot 
of space to work with, then go 
ahead and use it. The use of more 
space will improve performance 
and reduce program size and com- 
plexity. Likewise, if you’re tight on 
memory, then look for ways to 
swap speed for space. Also, disk 
space can become critical as well, 
especially if you’re using diskettes. 


How many instances of the data 
structure will you need? There’s 

a difference between maintaining 
an address list of a few friends, 
and writing a database program to 
track 25,000 students. In the first 
case, you can store a lot of infor- 
mation for each friend, since 
you're unlikely to run out of mem- 
ory. In the second case, every byte 
in a record definition adds 25K to 
the database size, and memory 
disappears in a hurry. 


How critical is performance? In 
the case of the graphics package, 
performance was extremely crit- 
ical, so I elected to use a large 
amount of memory for the lookup 
tables, rather than to use a small, 
simple subroutine to perform the 
byte-and-bit calculations. Even 
though memory was also very 
tight, I chose to go for perfor- 
mance and look for memory sav- 
ings elsewhere. 


DESIGNS ON DATA 


Data structure design, like algo- 
rithm design, is both a science 
and an art. There are rules, guide- 
lines, and even formulae that you 
can apply in order to figure out 
the best solution to a given prob- 
lem. At the same time, an instinct 
for quickly narrowing down the 
choices comes with time and prac- 
tice—practice that includes a fair 
amount of trial and error. The 
trick is to be aware of the possibil- 
ities, and to look for new and dif- 
ferent solutions, rather than to 
always adhere to the same old 
methods. It may turn out that the 
old approach was the better one, 
but that’s valuable information as 
well. As always, the best way to 
hone your programming skills is 
to sit down and write programs. 

In the next issue of TURBO 
TECHNIX, 111 continue with part 
three of this discussion, where I'll 
compare linked lists and arrays. In 
the meantime, happy coding. @ 


Bruce Webster is a computer merce- 
nary living in California. He can be 
reached on MCI Mail (as Bruce Web- 
ster), and on BIX (as bwebster). 


Listings may be downloaded from 
Library 1 of CompuServe forum 
BPROGA, as EDT.ARC. 
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LANGUAGE 


Assembler. 


Philip Seyer 


ecause of its early association with the Jap- 
anese fifth-generation supercomputer proj- 
ect of the 1990s, Prolog has been called a 
fifth-generation language. Assembly lan- 
guage, on the other hand, gets as close to the nuts 
and bolts of the computer as is possible without us- 
ing binary. One wonders, then, why the Turbo 
Prolog programmer would ever consider “dirtying” 
his/her hands with something as low-level as assem- 
bly language. Actually, there are a number of very 
good reasons to link your Turbo Prolog routines with 
Turbo Assembler. Two reasons that immediately 
come to mind are the resulting increase in speed 
and the reduction in code size. Another reason to 
use Turbo Assembler is to perform some of the low- 
level functions that are difficult to handle in Turbo 
Prolog. In this way, you can develop new predicates 
to further extend the capabilities of Turbo Prolog. 

This article will take you step-by-step through the 
Turbo Prolog/Turbo Assembler connection. In the 
process, I'll examine how a Turbo Assembler pred- 
icate is created, and will show how to pass simple 
data types between the two languages. Ultimately, 
you'll walk away from this article with two new pred- 
icates—open and read—to open and read binary 
files. 


READING BINARY FILES 


Turbo Prolog provides the filemode predicate to 
open files in either text or binary mode. In text 
mode, Turbo Prolog translates certain characters so 
that the file is more readable. For instance, the se- 
quence ODOAH is interpreted as a carriage return/ 
line feed, which generates a new line. Binary mode, 
on the other hand, allows your program to read a 
file without making any such conversions. Since this 
process is particularly useful when reading binary 
files, this mode is called binary mode. 
Unfortunately, a couple of characters are special 
in Turbo Prolog. One such character, [AH, marks 
the end of a file. Therefore, whenever a file is read 
in binary mode and the character 1AH is encoun- 
tered, Turbo Prolog thinks the job is done and ig- 
nores the rest of the file. One solution to this di- 
lemma is to write an assembler routine to read the 


file. 


CONNECTIONS 
Turbo Prolog 2.0 meets Turbo 


DUMP.PRO (Listing 1) shows a simple Turbo 
Prolog program that calls two assembly language 
modules. This program opens a file, reads each byte 
from the file, and then displays the bytes on the 
screen. DUMP reads any file, including binary files, 
and shows how to pass simple data types from Turbo 
Prolog to Turbo Assembler. 

Starting with the run predicate in Listing 1, the 
program creates a window, prompts the user for a 
filename, and then passes the filename to the read- 
FILE predicate: 
readFILE(Fi LeNAME): - 

open(Fi LeNAME, Fi leHANDLE), 

FileHANDLE <> 255, 

repeat, 

read(FileHANDLE, 
NumberBYTESread, ReadBUF ), 
processBYTE(NumberBYTESread, 
ReadBUF ), 

NumberBYTESread = 0,!. 
readFILE takes the filename that is passed to it, and 
immediately calls open (which is written in Turbo 
Assembler). 

The first argument of open contains the name of 
the file to be opened (this filename is declared as a 
string). The second argument returns an integer 
value that corresponds to the file handle created 
when open opens the specified file. If the file can’t 
be opened, then open returns the value of 255. The 
statement that follows the call to open checks to 
make sure that FileHANDLE is not equal to 255. If 
FileHANDLE is set to 255, this statement fails, caus- 
ing Turbo Prolog to backtrack to the second read- 
FILE clause: 
readFILE(FileNAME):- !, 

removewindow, 

write("Sorry, unable to open ", 

FileNAME,"."),nl, 

exit. 

In the case where open returns a valid file handle, 
readFILE enters the repeat loop (for more on re- 
peat loops, see “Failing With Grace,” TURBO TECH- 
NIX, July/August, 1988). The repeat loop continually 
calls read (also written in Turbo Assembler) to read 
a byte from the file that was just opened, and calls 
processBYTE to write that byte on the screen. 
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read takes FileNAME as its first argument, and re- 
turns two integer arguments: NumberBYTESread 
and ReadBUF. Normally, NumberBYTESread is set 
to 1 to indicate that a single byte has been read from 
the file. ReadBUF contains an integer that repre- 
sents the ASCII code for the byte that was read from 
the file. Next, NumberBYTESread and ReadBUF 
are passed to processBYTE, which displays on the 
screen the ASCII code of the character in ReadBUF. 
(Of course, this routine could also process the input 
byte in many other ways.) 

The terminating condition, NumberBYTESread = 
0, returns true when the end of the file is reached, 
and terminates the repeat loop. Once the condition 
NumberBYTESread = 0 succeeds, readFILE also 
succeeds and control returns to run. Since there are 
no more subgoals to execute, the program ends. 


INTERFACING CONSIDERATIONS 


When passing an argument to an assembler routine, 
Turbo Prolog pushes that argument onto the stack. 
Turbo Prolog may push either the actual value of the 
argument or the address of the argument, depending 
upon the argument’s data type. If the argument is an 
integer, for instance, the actual value is placed on 
the stack. On the other hand, if the argument is a 
string, then the address goes on the stack. Table | 
summarizes the manner in which arguments are 
passed onto the stack. 


IF THE AND THE WHAT IS PUSHED 
ARGUMENT IS: VARIABLE IS: ONTO THE STACK IS: 
An output argument Any data type 4-byte address of the 


output argument 


An input argument String, symbol, or 


compound object 


4-byte address 


An input argument Integer 2-byte value 

An input argument real 8-byte value (IEEE 
format) 

An input argument Char 2-byte value 


Table 1. A summary of how various data types are pushed 
onto the stack. 


There’s no need to worry about the data type of 
return arguments, since Turbo Prolog always passes 
return values by reference. 

In addition to passing arguments to the assembler 
routine, Turbo Prolog pushes a four-byte return ad- 
dress onto the stack. This address is the location of 
the next instruction in the Turbo Prolog program 
where execution is to continue after the assembly 
language predicate finishes its work. For instance, 
consider the call to open, which passes two argu- 
ments: 
open( Fi leNAME , Fi leHANDLE) 


Recall that FileNAME is a string variable. According 
to Table 1, Turbo Prolog pushes the address of a 
string on the stack. Thus, the first argument on the 
stack is a four-byte address. Since FileHANDLE is a 


return value (as designated by the output flow pat- 
tern in the global declaration), FileHANDLE is also 
passed as a four-byte address. Figure 1 shows what 
the stack looks like when open (in Listing 2) first 
starts its work. These initial conditions are called the 
activation record for the Turbo Assembler module. 


BOTTOM 


Address of FileNAME 


4 bytes 


Address of FileHANDLE 4 bytes 


Return address to Turbo Prolog routine | 4 bytes 


TOP 


Figure 1. The activation record for OPEN.ASM. 


It’s good practice to push the contents of the base 
pointer (BP) onto the stack in order to keep the base 
pointer out of harm’s way. That’s because the calling 
program needs the contents of BP to be preserved. 
This step is performed as follows: 


PUSH BP 
MOV BP, SP 


Now BP, instead of the stack pointer (SP), can be 
used to access the stack. Keep in mind that whenever 
something is pushed onto the stack, the location of 
all of the items on the stack is changed. Figure 2 
shows what the stack looks like after BP is pushed 
onto it. 


BOTTOM 
+10 Address of FileNAME 4 bytes 
a Address of FileHANDLE 4 bytes 
Return address to Turbo Prolog routine 
2 bytes 


+0 


TOP 


Figure 2. The status of the stack after pushing the base 
pointer. 


DOS interrupt 21H (function 3DH) is used to open 
the file specified in DS:DX. This function requires 
that the string that represents the filename be an 
ASCIIZ (null-terminated) string. Since Turbo Prolog 
stores its strings as ASCIIZ strings, there’s no need to 
convert the string. 

To get the address of FileNAME, the segment of 
the address must be moved into DS, and the offset of 
the address must be moved into DX. As you can see 
from Figure 2, the offset is at the position BP + 10, 
and the segment is at BP + 12. 


MOV DX, [BP]+ 10 
MOV DS, [BP]+ 12 


continued on page 142 
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LISTING 1: DUMP.PRO 


/* 


NOTE: This program Links in two external object 
files: open.obj and read.obj. Assemble these 
files using Turbo Assembler. Be sure to compile 
this program as a project. 


If compiling as a project, create a project file 
called "dump.prj" with the following text: 


simple 
open 
read 


To compile, choose "Project" from the "Compile" 
pulldown menu, and select the appropriate project file. 
my 


PROJECT “SIMPLE” 


global DOMAINS 
file = infile 
STRINGLIST = STRING* 
INTEGERLIST = INTEGER* 


GLOBAL PREDICATES 


Open(STRING, INTEGER) - (1,0) language asm 
read( INTEGER, INTEGER, INTEGER) - (i,0,0) language asm 


PREDICATES 


run 
readfile(STRING) 
repeat 
processBYTEC INTEGER, INTEGER) 


run. 


CLAUSES 


L[ERERRERRAARRERRERERERERERRA ED run RRARRAAARAERRAARRAAARRERRRRARER / 
run if 


makewindow(1,7,7,"Test of OPEN and READ routines ",0,0,25,80), 
cursor (5,10), 

write("Enter filename: "), 

read|n(Filename), 

clearwindow,nl,nl, 

readFILE(FileNAME). 


[MetAnAAnARAAAKRAAAAAARERAAAEE readfjle TH*AAAAAARARRRRKA RRA RARER / 


readFILE(FileNAME) if 
open(FileNAME, Fi leHANDLE), 
Fi leHANDLE <> 255, /* Check for error in opening file */ 
repeat, /* we backtrack to here if not EOF */ 
read(Fi leHANOLE ,NumberBYTESread, ReadBUF), 
processBYTE(NumberBYTESread, ReadBUF ), 
NumberBYTESread = 0,!. /* Check for end of file. */ 
readFILE(FileNAME) if !, 
removewindow, 
write("Sorry, unable to open ",FileNAME,"."),nl, 
exit. 


[TARRRAERRRENRARANHAERAEREAEREH Penegt HHHANAAERAERRNR ARERR RNR N ERED / 


repeat. 
repeat if 


repeat. 


[tetaeneneeneneERERAREEEEERE® DrocessBYTE RARER AR AR RRR RRRERE ERR EE / 


processBYTE(NumberBYTESread,ReadBUF) if 
NumberBYTESread <> 0 
write(ReadBUF," "), I. 

processBYTE(0,_) if !, 


nl, 
write("End of file."), 
nl. 


[IIR RAITT END OF DUMP. PRO * #8 tei toi ieie iii 7 
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LANGUAGE CONNECTIONS 
continued from page 141 


Before calling function 3DH, we need to take care 
of a few other registers. First, set AL to zero to 
specify that we want to open a file for reading. Since 
AH specifies the function call, set AH to 3DH. 

Once the registers have been set, make the call to 
int 21. If no problems arise, then interrupt 21H 
opens the file and returns the file handle in the AX 
register. If DOS cannot open the file, the carry flag 
is turned on. The following instruction lets us easily 
check if the carry flag is set: 


JC FAILURE 


This instruction says, “If the carry flag is set, jump to 
FAILURE.” If the carry flag is not set, the address of 
the file handle is assigned to DS:DI via the LDS 
instruction: 


LDS DI,DWORD PTR [BP] + 6 


Next, move the contents of AX to the output argu- 
ment, and restore the DS and BP registers. There is 
one final bit of cleanup to do before control is 
returned to Turbo Prolog. Eight bytes must be 
popped off the stack for FileNAME and 
FileHANDLE (four bytes each). 

Listing 4 shows the read routine that actually 
reads the file that was just opened. The module is 
straightforward and well commented, so I'll leave 
this module as an exercise for the reader. The 
overall connection is similar to the open routine. Be 
sure to save the original base pointer, and to move 
the stack pointer to BP. Also, don’t forget to save 
Turbo Prolog’s data segment. When returning to 
Turbo Prolog, remember to restore the original base 
pointer, along with the data segment. Finally, pop all 
“pushed” parameters off the stack. 


ONE STEP BEYOND 


This example demonstrates how to pass simple data 
types, such as strings and integers, between Turbo 
Prolog and Turbo Assembler. A number of unan- 
swered questions still remain. For instance, there’s 
the question of how to handle complex structures, 
such as lists or compound objects. In addition, you'll 
need to know how to allocate memory for structures 
in Turbo Assembler in a way that’s acceptable to 
Turbo Prolog. Finally, you may want to call a Turbo 
Prolog predicate from Turbo Assembler. The an- 
swers to these questions will be the subject of a fu- 
ture “Language Connections.” @ 


Philip Seyer is a composer, writer, and microcomputer 
analyst. He is coauthor of Turbo Prolog Advanced Pro- 
gramming Techniques, TAB Books, Inc. 


Listings may be downloaded from Library 1 of 
CompuServe forum BPROGB, as PROASM.ARC. 


LISTING 2: OPEN.ASM 


COMMENT Q****®8ee eek k eee eee RRR REAR REAR RARE HR RERR EERE RE RER EERE CH 


This program receives the address of an ASCIIZ string (a string 
that ends with a binary zero). The string contains the name of 
8 file that is to be opened. The program opens the file and 
returns an integer that acts as a file reference (also called 
a file handle). We return the file handle by placing its 
address on the stack. 


o 


<--- FIRST PARM (INPUT PARM) 


<--- SECOND PARM (OUTPUT PARM) 32 BIT POINTER 


RETURN ADDRESS 


Om NWEYUAN@WO— 


A_PROG SEGMENT BYTE 
ASSUME CS: A_PROG 
PUBLIC open_0 
open_O0 PROC FAR 
MOV SI,DS 
PUSH BP 
MOV BP,SP 


ysave SI 

ysave BP on stack 

7BP = SP 

OX, [BP]+ 10 jget offset address of filename 
DS, (BP]+ 12 get segment addr. of filename 
AL, AL 7Set Al to 0 for read access 
AH, 30h 7Specify open function 

21h ;Invoke the interrupt 


FAILURE 
DI,DWORD PTR [BP] + 6 ;make DI point to output parm 
SUB AH, AH ; 


(D1] ,AX 7Move AX to FileHANDLE 

BP ;Restore BP 

OS,SI Restore DS 

8 ;pop the parms off the stack 

FAILURE: 

AX, OFFh jOFFh will be error flag 

DI,DWORD PTR [BP] + 6 ;Make DI point to output parm 
jMove error value to FileHANDLE 
7Restore BP 
7Restore DS 
ypop the parms off the stack 


open_0 ENDP 


A_PROG ENDS 
END 


LISTING 3: READ.ASM 


This program receives an integer on the stack that refers to 
an open file. This number is called a file handle. The 
Turbo Prolog program gets the file handle by calling the 
assembly language predicate "open." FileHANDLE appears at 
offset 14 on the stack. 


BOTTOM OF STACK 


<--- Ist PARM (INPUT) FileHANDLE ( 2 bytes) 


<--- Address of 2nd PARM (OUTPUT) NumBYTESread 


<----Address of 3rd PARM (OUTPUT) DataBUF (4 byte pointer) 


<--RETURN ADDRESS 


A_PROG SEGMENT BYTE 
ASSUME CS: A_PROG 
ASSUME DS: A_PROG 
PUBLIC read_0 
read 0 PROC FAR 
MOV AH,3Fh AH = 3F means read file 
INT 3 This causes program to halt 
; under debug 


PUSH BP 
MOV BP,SP 
MOV SI,DS 


; Save base pointer on stack 
Set BP to SP 
Save Turbo Prolog program's 
; data segment address 


MOV CX,1 ; CX must contain number 


; of bytes to read 
Set DS:DX to point to addrress DataBUF 


MOV DS, [BP]+8 
MOV DX, [BP]+6 


7Put high word in DS 
;Put low word in DX 


MOV BX, [BP]+ 14 7 get file handle from stack 


Before calling INT 21, make sure these conditions 
are satisfied: 

AH 3FH 

BX = file handle 

CX = number of bytes to read 

DS:DX point to the address of the input buffer 


INT 21h 
JC FAILURE ; If carry flag is set 


; jump to FAILURE 
Zero out the hibyte of the DataBUF variable 


MOV DI,DX ; DI -> lowbyte 
IWC DI 7 Make DI point to hibyte 
MOV BYTE PTRI[DI],00h ; Move zero to hibyte 


AX shows the number of bytes read. So now we 
return this information to Prolog 

DI,DWORD PTR [BP] +10 Make DS:DI point to 
the NumBYTESread variable. 
Move AX to NumBYTESread 


[D1] , AX 


BP 
DS, SI 


Restore the Base Pointer 
Restore calling progs data 
data segment 

Pop the parms off the stack 
44442 


10 


see se ee 


FAILURE: 
MOV AX, OFFh 
LOS DI,DWORD PTR [BP] + 10 
MOV [DI] ,AX 
POP BP Restore BP 
MOV DS,SI Restore DS 
RET 10 ; Pop the parms off the stack 
; The 10 after RET is critical. Without it, the return to 
; Turbo Prolog will be fouled up. 


OFFh is hex for -1 
Set NumBYTESread to -1 
To show read failure 


wee eee 


We put 10 after RET here because we need to pop the parameters 
that were pushed on the stack when this routine was called. 
This routine receives 3 arguments on the stack: 


Fi LeHANLE (2 bytes) 

NumBYTESread (4 byte pointer) 

DataBUFF (4 byte pointer) 
2+4+4 = 10, hence the 10 after RET 


read_0 ENDP 
A_PROG ENDS 
END 
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TALES FROM THE 


RUNTIME 


he fundamental purpose of the Runtime is 

to provide a common set of building blocks 

with which you can more easily and quick- 

ly construct applications. Starting with this 
column, we turn for a while to the addition of signif- 
icant and useful new building blocks. 

Our first building block is a basic command parser 
and handler. Many applications use command lines. 
Even if you’re not interested in building such an ap- 
plication, this example shows how to integrate a 
completely new building block into the Runtime. 


THE TALE 


A command handler insulates you from the messy 
details of reading and parsing a command line. It 
handles leading spaces, ignores blank lines, lets the 
user delete characters, and searches for a command 
match. The command handler presented in this ar- 
ticle also includes a routine, cmd_file, that redirects 
input from the standard input file (stdin) to another 
file. 

The command handler is driven with a list of com- 
mand keywords. The list should contain one or more 
entries of the structure type cmd_key (see CMD.H, in 
Listing 1), Each entry in the list has three compo- 
nents: a command keyword, a routine to call for that 
command, and a pointer to the next entry. The “next 
entry” pointer for the last entry must be null. 

The command handler is fairly straightforward to 
use. First, declare a list of command entries. (You 
must write the routines for each of the commands. 
Fortunately, those routines are the functions that 
your application provides.) The command prompt is 
established by calling emd_init with a prompt string. 
Next, call cmd_read to get a line of input from the 
user. Finally, call the command parser, cmd_parse. 

cmd_parse returns either a pointer to the com- 
mand entry that matches the user’s entry, or else a 
null pointer. cmd_parse also returns the rest of the 
command line if the user entered a valid command. 
A null pointer indicates that the user’s input did not 
match a command. In this case, you can call cmd_- 
error to print a standard error message. 

The command handler also handles lines that 
contain several commands in a row. For example, 
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Reading the command line 


Bill Catchings and Mark L. Van Name 


consider the following command line: 
SET FOO ON 


In this case, cmd_parse returns the command SET, 
and moves the start of the input line to the “F” in 
FOO. Call cmd_parse again to parse FOO. Finally, 
call cmd_parse a third time to parse ON. 

It’s important to note that, even though the com- 
mand entry structure (cmd_key) contains pointers to 
routines, the command handler does not use those 
pointers. The programmer must call the routine for 
the command that cmd_key returns. This design lets 
your program ignore those routines in some cases, 
and possibly to not provide these routines for some 
entries. This flexibility is useful, for example, when 
cmd_parse must get both a command (for which you 
probably would call a routine) and its arguments (for 
which you would not call a routine). 

The complete command handler is in two files: 
CMD.H (Listing 1) and CMD.C (Listing 2). We sug- 
gest that you place CMD.H into your standard Turbo 
C include directory (usually \TURBOC\INCLUDE), 
since you need to include CMD.H in order to use the 
command handler. 


THE RUNTIME 


This article assumes that you’ve already loaded the 
Runtime source and built all of its libraries. If you 
have not, use the Runtime’s install procedure to 
build the directories and load the source files (see 
“Tales From the Runtime,” TURBO TECHNIX, July/ 
August, 1988). Then change directories to the Run- 
time’s CLIB directory (usually \TURBOC\LIBRARY- 
\CLIB), and use the following two batch file com- 
mands to build all of the objects and libraries: 
CLIB all -I\turboc\include 
CLIBRLIB 

In addition, you must tell Turbo C to use these 
libraries rather than the standard libraries. To do so, 
run TC and select Options/Directories/Library di- 
rectories. Assuming that you’ve used the standard di- 
rectory structure from our earlier columns, enter the 
following directories: 
C:\TURBOC\LIBRARY\CLIB; 
C:\TURBOC\LIB 
Turbo C now checks the modified libraries first, and 
then looks into its standard LIB directory for any- 


thing that’s not in those libraries. Choose Options/ 
Store Options, and be sure to answer “Y”’ when 
Turbo C prompts you to overwrite TCCONFIG.TC. 

The next step is to add the new routines to the 
libraries. Change directories to the CLIB Runtime di- 
rectory, copy CMD.C to that directory, and then enter 
the following batch file command: 


CLIBREPL all cmd.c -1I\turboc\include 


This batch file command updates all of the memory 
model libraries. You'll get the following warning 
message when you run this batch file for the first 
time: 


Warning: ‘CMD’ not found in the library 


This warning message appears because CLIBREPL 
removes each old object from the library before it in- 
serts the new object. Since our routines are not yet in 
those libraries, CLIBREPL cannot remove them; 
thus, it gives the warning and then adds our rou- 
tines. If you repeat this process later, you won't get 

a warning. 


TAKING ORDERS 


CMDTEST.C (Listing 3) tests the command handler. 
Since we’ve heavily commented CMDTEST.C, we'll 
only touch on a few key points that may not be 
obvious. 

To avoid problems with forward references, de- 
clare the routines for each command (exit, prompt, 
and execute) first. The problem of forward refer- 
ences occurs when you use a routine in a file before 
you present its code, as we do here. Without these 
declarations, the compiler complains that it doesn’t 
know these routines when it encounters calls to 
them. An alternate solution to this problem is to 
change the order of the routines, so that each rou- 
tine appears before it’s used. 

Place the commands into an array, main_cmd{], of 
cmd_key structures. Initialize each element of the ar- 
ray to point to the next element (with the exception 
of the last element, which must be a null pointer). 
You don’t have to worry about declaring the size of 
the array; the use of brackets ([]) forces the compiler 
to handle that for you. While this example uses an 
array, that’s not a requirement. Also, the command 
entries must be in a linked list, but their order 
doesn’t matter. 

You can also use the same routine for more than 
one command, as shown by “exit” and “quit.” Both 
of these commands use the standard C exit routine. 

The main program of CMDTEST.C uses cmd_init 
to set its prompt. The program continues to get com- 
mands until the user enters “exit” or “quit” on the 
command line. The loop first calls cmd_read to read 
a line, and then calls cmd_parse on that line to get 
a command (along with any arguments). If cemd_- 
parse returns zero, the user did not enter a legal 
command, so cmd_error is called. If the user en- 


tered a legal command, the loop calls the routine as- 
sociated with that command, which is located in the 
main_cmd{] array. That routine is then passed with 
the rest of the command line. The command’s rou- 
tine could use cmd_parse to parse the rest of the 
command line, although we do not do so in our 
example. 

execute uses cmd_file to redirect the command 
handler’s input to the file whose name the user en- 
tered. prompt uses cmd_init to change the prompt to 
the string that the user entered after “prompt.” 


INSIDE THE COMMAND HANDLER 


As with CMDTEST.C, CMD.H and CMD.C are 
heavily commented, so we suggest that you read 
them for a detailed explanation of the command 
handler. We will only touch on the high points here. 

The main contribution of CMD.H is the command 
entry data structure, cmd_key, which is described 
above. CMD.H also contains constants that limit the 
maximum line and prompt sizes, plus templates for 
all of the command handler’s routines. 

CMD.C contains the source code for the routines. 
All of those routines share common variables that 
contain the input line, the prompt string, and point- 
ers to the input and output files. 

To avoid problems encountered when writing 
prompt in CMDTEST.C, cmd_init copies the prompt 
string to the command handler’s internal prompt 
variable. We initially left the new prompt in the input 
buffer, which is where the new prompt is entered by 
the user. Since we saved only a pointer to that 
prompt, however, new text typed by the user ap- 
peared as the prompt the next time the command 
line was displayed. To avoid that problem, we main- 
tained our own copy of the prompt string. 

When a command does not match the command 
line, cmd_error simply displays an error message. 
You could place more sophisticated error handling 
into the program at this point, if you chose to do so. 

cmd_file changes the command handler’s input 
file. After the caller opens the input file, cmd_read 
reads that file, closes it, and returns to stdin for in- 
put. This approach precludes nested command files, 
a loss that we decided was not significant for the 
basic command handler. 

cmd_parse parses the command line. The argu- 
ments to cmd_parse are the input line to be parsed 
and the linked list of possible commands. cmd_parse 
uses cmd_token to get the first token, and then se- 
quentially searches the list of possible commands, 
using cmd_compare to compare the token with each 
command key. cmd_parse handles exact matches, 
one or more partial matches, and no match. If an 
exact match or only one partial match occurs, then 
cmd_parse returns the matching key. Otherwise, it 
returns zero. 

cmd_compare compares the user’s entry with the 
possible command keywords. cmd_compare returns 
CMD_MATCH for an exact match; otherwise, 
it returns CMD_NOMATCH. The constant 
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LISTING 1: CMD.H 


void cmd_init( prompt ) /* Note that it returns nothing. */ 
char *prompt; 
€ 


/* This file contains the information that we include in = 
the command handler, CMD.C. stincpyt jem promt, prompt, (GG PRBAN); 
5 > /* end routine cmd_init() */ 
We store the set of legal commands in a linked list of = 
the following structures. The entry for each command 
contains the command's keyword, followed by the function 
that we are to call if the user enters that keyword, 
and then a pointer to the entry for the next command. 
The last entry has a zero in this pointer field. 

The command handler tries to match the command that a 
user enters with one of these command keywords. */ 


/* The cmd_error() routine is more of a placeholder than anything 
really useful. It just prints a generic error message. It 
has no arguments and does not return a value. */ 


void cmd_error() 
€ 
printf( "No command matches what you entered.\n" ); 


typedef struct cmd_key_st 
€ 


> /* end routine emd_error() * 
char “keyword; = at 


void (*function)(); 
struct cmd_key_st *next_key; 


/* The next routine, cmd_file(), lets the caller re-direct the 
> cmd_key; Mu 


command handler's input from its default (or previous) source 
toa file, It takes the file pointer of that file as its 
* 
/* We define several general command handler constants. */ CORY Bimmer ts Tete toea noe net urTi ls) value-nr/ 
void cmd_file( ifp ) 
FILE *ifp; /* pointer to the file that is to be the new 
input source */ 


#def ime CMD_MAX 256 /* Maximum input line size */ 
#def ime CMD_PR_MAX 40 /* Maximum prompt size */ 


€ 
/* Remember that the command handler gets its input from 
the file associated with the file pointer cmd_ifp. */ 
emd_ifp = ifp; 


/* We also define here all of the routines in CMD.C for any 
routine that might need to call them. Note that we define 
the arguments for each routine so that Turboc C can 
verify that ok calls to them use parameters of the /* end routine cmd_filec) */ 
correct type. */ 

void cmd_init( char *prompt ); 

void cmd_error(); 

void cmd_file( FILE *ifp ); 

int cmd_compare( char *key, char *token ); 

char *cmd_token( char **cmd_ptr ); 

cmd_key *cmd_parse( char **cmd_ptr, cmd_key *keys ); 

char *cmd_read(); 


/* cmd_compare compare a keyword with a token that cmd_parse has 
extracted from the user's input. 
It returns one of two codes: CMD_MATCH if the two strings match 
exactly, or CMD_NOMATCH if they do not exactly match. 


This is the routine where we would add partial keyword matching. 
It would return the code CMD_PART if the token were a substring 
of the keyword. */ 


int cmd_compare( key, token ) 
char *key, *token; /* the command and token it is to compare */ 
€ 


LISTING 2: CMD.C 


int match; /* to get the comparison result from strempi() */ 

/* This file contains the code for our command handler. */ z 2 - 

/* We use the standard library function strcmpi() to do the 
comparison. It does a case-insensitive comparison. */ 


/* First we include several standard C include files, and - 
match = strempi( key, token ); 


then we include our command handler's include file, CMD.H. */ 


/* Wow return the proper status -- 0 indicates a match. */ 
if ( match == 0 ) 

return( CMD_MATCH ); 
else 

return( CMD_NOMATCH ); 


#include <stdio.h> /* For standard 1/0 functions */ 
#include <conio.h> /* For console 1/0 functions */ 
#include <string.h> /* For string manipulation functions */ 
#include <cmd.h> /* Our command handler's include file */ 


/* Now we define several constants that we use throughout the /* end routine cnd_compare() */ 
command handler. These are result codes that cmd_compare() 
can return as it is comparing what the user entered to the 


set of legal keywords. */ /* cmd_token() finds the first "token" in a line of user input. 


We define a token to be a string of characters that contains 
no spaces and that is followed by either a space or an 


#define CMD_NOMATCH 0 ‘* Input did not match any keyword */ 
‘a fee Mee end-of-string null (\0). 


Wdefine CMD_MATCH 1 /* Input matched a keyword exactly */ 
#defime CMD_PART 2  /* Input matched a substring of a A p 
keyword */ The input string should not contain any non-printable 
characters (such as carriage return or line feed), and it 
must be terminated by a null. It is up to the caller to make 
sure that this condition is true. Note that cmd_read() always 
returns 8 string terminated by a mull, so this condition should 
not be a problem. 


/* Now we define several variables that we use throughout the 
command handler. */ 


char cmd_buffer{ CMD_MAX ]; Input Line buffer */ 

char cmd_prompt{ CMD_PR_MAX ] Storage for the prompt */ 

FILE *cmd_ifp=stdin; Input file pointer. 
Initially we get all input 
from the standard input 
device. */ 

FILE *cmd_ofp=stdout; Output file pointer. 
Initially we get all output 
from the standard output 
device. */ 


This routine has one argument, a pointer to a pointer to a line 
of imput text. 


After it finds the first token, it moves the input line pointer 
to point to the first character after the space after that 
token. (It replaces that trailing space with a null.) If the 
token ends with a mull rather than a space, this routine leaves 
the input line pointer pointing at the null. */ 


char *cmd_token( cmd_ptr ) 

char **cmd_ptr; /* pointer to a pointer to a line of input text */ 
/* Now we define the command handler's functions. Note that € 
by defining every function before we use it we avoid all 
forward reference problems. */ 


char *save ptr, /* pointer to the start of the input line */ 
*tmp_ptr; /* pointer to our current position in the 
input line */ 
The first function, cmd_init(), sets the command handler's /* Start both of our work pointers at the beginning of the line */ 
prompt. It does so by copying the prompt string from the 
container in which the caller passed it to our internal 
storage. It uses the standard Turbo C string copy function, 
and it copies up to the maximum prompt size. It does not 
return a value. */ 


Listings continue on page 148 
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TALES FROM THE RUNTIME 
continued from page 145 


CMD_PART is defined for the case where the user’s 
input token is a substring of the keyword. cmd_parse 
is designed to handle that case, but cmd_compare 
does not yet check for partial matches. This is a po- 
tentially important enhancement. 

cmd_compare uses the standard library routine 
strcmpi to do a case-insensitive comparison. strempi 
returns 0 for a match. If no match occurs, strempi re- 
turns a negative or positive number to indicate 
which string is lexically “greater.” 

cmd_token finds and returns the first token in the 
input line that it receives as an argument. cmd_token 
also updates the pointer to that line to point to the 
first character after the space that follows the token. 
A token is defined in the program as a string of non- 
space characters followed by a space, or by a null 
character that marks the end of the string. The caller 
of cmd_token must ensure that the input line ends 
with a null. (The string returned by cmd_read is so 
terminated.) 

cmd_token accepts all characters up to a space or 
a null. If cmd_token encounters a space, it replaces 
that space with a null, moves the input pointer past 
the space, and returns the token. If cmd_token en- 
counters a null, it returns the token that it feund, if 
any. cmd_token ignores all spaces at the beginning 
of the line. 

cmd_read gets a line of input either from the con- 
sole (stdin) or from a command file that is set by 
cmd_file. cmd_read also handles I/O chores such as 
echoing characters, ignoring leading spaces and 
empty lines, and deleting characters. 

cmd_read uses getch to read from the console. 
getc is used to read from a file because gete only re- 
turns input when the user terminates the line by 
pressing Enter. Our program must examine every 
character, not just the entire line, so that we can pro- 
vide command editing features. 

One consequence of this choice is that input redi- 
rection at the DOS level will not work with our com- 
mand handler. Fortunately, this is generally not a 
problem for an interactive command line parser. 

cmd_read puts most of the characters that it en- 
counters into the input buffer. Newline characters 
and carriage returns are treated in a special way, 
since they mark the end of a line. cmd_read also 
handles an end-of-file character, which causes cmd_- 
read to close the input file and then reset the com- 
mand handler to read from the console. Backspaces 
receive special treatment as well, because they are 
used for character deletion. Spaces are handled dif- 
ferently because they must be echoed on the screen, 
but ignored at the beginning of a line. 

This design has two small flaws. First, because 
cmd_read ignores leading spaces and does not put 
them in the input buffer, they cannot be deleted. 
Second, if the user enters any other nonprintable 
characters, cmd_read puts them in the input buffer 


and passes them along. Remedies to these two flaws 
would improve the command handler. 


ANOTHER TALE 


We've already noted several useful improvements 
that you could make to this basic command handler. 
Many others are also possible, such as support for 
more than keyword parsing, with special codes for 
such things as numbers, filenames, and dates. You 
could also improve the basic data structure, perhaps 
by making the function field a union of a function, 
a pointer, or a number. With this modification, the 
caller could do more with the parsed command than 
just call a routine. 

Our next column will focus on one “enhance- 
ment” that is, in itself, a useful building block: 
improvements to cmd_read. A number of improve- 
ments can be made, including the ability to support 
the DOS command-line editing functions. But, that’s 
another tale. & 


Mark L. Van Name is a freelance writer. Bill Catchings is 
a freelance writer and a software engineer at Data General 


Corp. 
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save_ptr = tmp_ptr = *cmd ptr; 


/* Loop until we hit a null. */ 
while ( *tmp_ptr != '\O' ) 


/* If we are on a space, we must process it. If not, we 
just increment the Line pointer and move on. */ 

if ( *tmp_ptr == ' ' ) 

€ 


/* If the space is at the beginning of the line, we 
ignore it by incrementing both our work and initial 
line position pointers, and then continuing in the 
loop to get the next character. */ 

if ( tmp_ptr == save_ptr ) 

< 

tmp_ptr++; 
save_ptr++; 
continue; 

> 

/* If we are not at the beginning of the line, we 
replace the space with a null, move the pointer 
to the next character, and exit the loop. */ 

*tmp_ptr++ = '\0'; 

break; 

> 
else 


tmp_ptr++; 
*cmd_ptr = tmp_ptr; /* Update input line pointer */ 
return( save_ptr ); /* Return pointer to token */ 


> /* end routine cmd_token() */ 


/* cmd_parse() gets the first token from the input line and tries to 
find a command that the token matches. It also moves the input 
line pointer past the token. It returns either the command entry 
that the token matched or, if there was no match, zero. 


It has two arguments: a pointer to a pointer to a line of input 
text, and a linked list of command entries. */ 


cmd_key *cmd_parse( cmd_ptr, keys ) 
char **cmd_ptr; /* pointer to a pointer to the input */ 
emd_key *keys; /* the linked list of commands */ 
{ 
char *token; /* pointer to the first token it finds */ 
emd_key *part_key=0L; /* a pointer to a command entry that 
the token partially matches, if any */ 
int match; /* return code from cmd_compare() */ 


/* Get the first token from the command line. */ 
token = cmd_token( cmd_ptr ); 


/* Now check to see if that token matches any of the command 
keys. Loop through the list of key entries and compare 
each key entry to that token. */ 

while ( keys I= OL ) 

€ 

match = cmd_compare( keys->keyword, token ); 


/* If the token matches an entry exactly, return that 
entry. */ 

if ¢ match == CMD_MATCH ) 
return( keys ); 


/* If we find a partial match for the first time, save 
@ pointer to that entry. If we find a partial match 
for the second time, the token is ambiguous, so we 


return no match (zero). */ 
if ( match == CMD_PART ) 
€ 
if ( part_key != OL ) 
return( OL ); 
else 
part_key = keys; 
>? 


/* If the token does not match the command key at all, we 
Move on to the next command key. */ 
keys = keys->next_key; 


> /* end while loop*/ 


/* If we fall through the loop and make it to this point, we 
did not find an exact match. If we found only one partial 
match, we treat it as an exact match and return the matching 
entry. Otherwise, we return no match (zero). */ 

if ( part_key t= OL ) 

return( part_key ); 
else 
return( OL ); 


/* end routine cmd_parse() */ 
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/* cmd_read() gets a line of input, either from the user or froma 


a file to which the user has redirected the command handler's 
input. 

emd_read() handles leading spaces and empty lines. It also lets 
the user delete characters. It considers a line to be text 

that is terminated by either a carriage return or a line feed. 


It takes no arguments. It returns a pointer to the input line. */ 


char *cmd_read() 


{ 


char *cmd_ptr; /* a pointer into the input buffer */ 
int c; /* temporary character holder */ 


/* start out pointing to the start of the input buffer */ 
emd_ptr = cmd_buffer; 


/* Display the prompt and then get input until the user 
terminates a line with a carriage return or line feed. */ 

printf( "\n%s", cmd_prompt ); 

while (1) 

€ 


/* If our global input file pointer points to stdin, 
use Turbo C;s console getch() function. This lets us 
see every character the user types, rather than having 
to wait until he enters a carriage return, as getc() 
does. We need to see every character to handle 
editing. Otherwise, use getc() to get input froma 
file. */ 

if ( cmd_ifp == stdin ) 
¢ = getch(); 

else 
c = getc( cmd_ifp ); 


/* Wow handle the input character. */ 
switch ( c ) 
€ 


/* If the input character is an end-of-file indicator, 

we must have just finished processing a command 

file. Close that file. Then reset our global input 

file pointer to point to standard input so that 

we can get more input interactively from the user. */ 
case EOF: 

if ( cmd_ifp != stdin ) 

€ 


fclose( cmd_ifp ); 
emd_ifp = stdin; 
> 
break; 


/* If the input character is a backspace, use it to 
erase the previous character. 
If we are at the start of the line, ignore it, 
because there is nothing to delete. 
Otherwise, print backspace, space, backspace to 
erase the previous character. Then backup the 
buffer pointer. */ 
case '\010': 
if ( cmd_ptr == cmd_buffer ) 
break; 
printf¢ "\010 \010" ); 
emd_ptr--; 
break; 


/* If the input character is either a carriage return 
or a line feed, we may be done. Echo a newline. 
Then, if we are at the beginning of the line, re-type 
the prompt and continue. 

Otherwise, we really are done with this line. Put 
a null in the buffer to terminate that string, and 
return a pointer to that buffer. */ 

case '\n': 

case '\r': 

putc( *\n', cmd_ofp ); 
if ( cmd_ptr == cmd_buffer ) 
€ 


printf( "Xs", cmd_prompt ); 
break; 

> 

*cmd_ptr = '\0'; 

return( cmd_buffer ); 


/* If the input character is a space, it matters 
whether we are at the beginning of the line. 
If we are, echo the space and ignore it. 
If not, treat it like any other character by 
falling through to the next case. */ 

case ' ': 
if ( cmd_ptr == cmd_buffer ) 
€ 


putc( ' ', cmd_ofp ); 
break; 
> 


/* We assume all other characters are printable ones 
that could be part of a command. We just copy them 
to the buffer and echo them on the screen. */ 

default: 

*cmd_ptr++ = c; 
putc( c, cmd_ofp ); 
break; 


> /* end the switch statement */ 
> /* end the character processing loop */ 


/* end routine cmd_read() */ 


LISTING 3: CMOTEST.C 


/* This file contains a simple program that tests our command 
handler. 


We include in it both the standard Turbo C I/O routines 
and our command handler include file. */ 


#include <stdio.h> 
#include <cmd.h> 


/* standard 1/0 routines */ 
/* Command parser definitions */ 


/* We define several of the routines in this file to avoid 
forward reference errors. */ 


void exit(); 
void prompt(); 
void execute(); 


/* main_cmd is an array of key entries that define our test's 
legal commands. We use the cmd_key structure from CMD.H. 
To show that more than one command can use the same action 
function, we make the exit and quit commands synonyms. 


We Link each entry to the next one by using the & operator 
to get the address of that entry. 

To make the last entry point to nothing else, we use a 0 
Pointer. (We coerce the 0 to long to make it 32 bits. */ 


emd_key main_cmd{) = € 
“execute", execute, &main_cmd[ 1], 
"exit", exit, &main_cmd[ 2], 
“prompt", prompt, &main_cmd[ 3], 
“quit", exit, (cmd_key *) OL 

yy 


/* The main program is a simple test that uses the command 
handler's functions. */ 


main () 
{ 
char *arguments; /* Pointer to the arguments that 
the command handler returns */ 
emd_key *main_ans; /* The command entry it returns */ 
/* First we initialize our command prompt. */ 
emd_init( "Cmd test>" ); 


/* Then we loop forever, processing commands. We exit the 
loop when the user enters exit or quit. */ 

while (1) 

{ 


/* First we get a line of input from the user. The 
string pointer that cmd_read returns points to the 
first command line that the user typed that 
contained something other than blanks. */ 

arguments = cmd_read(); 


/* We then call the command parser to parse that command 
line. We pass it the address of the address of the 
string it should parse, so that it can move the 
arguments pointer past the one command that it 
processes. In this way we can process a string of 
several commands by calling it with the same argument 
line repeatedly. 

We also pass it the address of the first entry in the 
linked list of command entries. 

cmd_parse returns the command entry from that table 
that matched the command the user entered. */ 


main_ans = cmd_parse( &arguments, &main_cmd[ 0 ] ); 


/* If cmd_parse returned a null command entry, then the 
user entered a command that did not match any of the 
legal options. In that case we call the command 
handler's error routine. 


If the user entered a legal command, we then call i 
routine with the remainder of the command line as i 
argument. */ 

if ( main_ans == (cmd_key *) OL ) 
emd_error(); 

else 
( *(main_ans->function) )( arguments ); 


>  /* end the command processing loop */ 
> /* end the main program */ 


Now we provide the routines for the commands jn our 
main_cmd structure. 

main_cmd[ 1 ] and main_cmd[ 3 ] both use the standard C 
function exit(). 


main_cmd[ 0 ] uses the routine execute(), which we 
define below. 


It executes commands from a command file whose name the 
user gives as an argument. It opens the file and passes 
its file pointer to the command handler's cmd_file() 
routine. */ 


void execute( file ) 
char *file; /* File of commands that we are to execute */ 
{ 

FILE *ifp; /* file pointer for that file */ 


/* If the file open fails, print an error message. 
If it succeeds, pass its file pointer (ifp) to cmd_file(), 
which will re-direct the command handler's input to that 
file. Then print a message that tells the user that the 
command handler is now executing the commands in that 
file. */ 
if ( Cifp = fopen( file, "r" ) ) == NULL ) 
printf( "Cannot open the file Xs\n", file ); 
else 
€ 
cmd_file( ifp ); 
printf( “Executing the commands in file %s\n", file ); 
> 


> /* end routine execute */ 


/* main_cmd[ 2 ] uses the routine prompt(), which we 
define below. 


It changes the command handler's prompt to the prompt string 
that the user entered by calling cmd_init() with that new 
prompt. */ 


void prompt( prompt_str ) 
char *prompt_str; /* the new prompt string */ 
. 

emd_init( prompt_str ); 


> /* end routine prompt() */ 
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CRITIQUE 


TURBO ASYNCH PLUS 
Blaise Computing, Inc. 
2560 Ninth Street, Suite 316 
Berkeley, CA 94710 

(415) 540-5441 

$129.00 


ight up there on the list 

of Great Unsolved Mys- 

teries, along with Ame- 

lia Earhart’s disappear- 
ance and the Loch Ness Monster, 
are the questions, “Why didn’t 
they put interrupt-driven com- 
munications into the PC’s ROM 
BIOS?”, and “Why doesn’t inter- 
rupt 14H buffer the characters 
that come in from the communi- 
cations line?” 

If you wish to roll your own 
telecommunications code in 
Turbo Pascal, this little enigma 
means that you can poll interrupt 
14H and content yourself with 
300-baud operation. Otherwise, 
you can handle interrupts directly 
by diving into the arcane lore of 
the 8259A PIC and 8250 UART 
and then, before giving up, use 
somebody else’s library. 

Designed for use with Turbo 
Pascal 4.0, Blaise Computing’s 
Turbo Asynch Plus is a library that 
effortlessly handles the messy de- 
tails of interrupt-driven asynchro- 
nous communications on PC, AT, 
PS/2, and compatible computers. 
Turbo Asynch Plus’ three diskettes 
contain the units (.TPU files), 
.OB] files, Pascal and assembler 
source code, project files for re- 
compilation, and sample pro- 
grams. 


A text file de- 
vice driver (TFDD) 
allows communica- 
tions ports to be 
treated as files via 
the use of Readln 
and Writeln 
statements. 


The sample programs include 
a file transfer program that uses 
XMODEM protocol, a checkout 
program that tests and demon- 
strates the various Asynch Plus 
functions, and a (somewhat lim- 
ited) terminate-and-stay-resident 
(TSR) program that performs 
background communications. 
Source code for the units is pro- 
vided, but an assembler must be 
used in order to change any of 
the assembly language code. 

Turbo Asynch Plus is organized 
into three levels for easier main- 
tenance and comprehension. The 
first level, which is called “Level 
0,” is written entirely in assembly 
language. This level handles the 
details of interrupt-driven com- 
munications, supports multiple 
ports, hardware and software flow 
control (DTR, RTS, and XON/ 
XOFF in combination), baud rates 
up to 19,200, and the data word 
formats that are normally avail- 
able through the BIOS. Level 0 
also handles the buffering of 
characters to and from the com- 
munications ports, and the use of 
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fixed-size circular queues that are 
provided by the caller. Level 0 
may be linked into the rest of your 
program, or else loaded separately 
as a TSR utility. 

The second of the three levels, 
“Level 1,” uses Level 0’s functions 
in order to provide a basic Turbo 
Pascal interface to the communi- 
cations ports. Level 1 calls Level 
0’s functions with the Turbo Pas- 
cal Intr() procedure. Level 1 al- 
lows you to set and read a port’s 
transmission options, read and 
write characters, and open and 
close the port completely from 
Turbo Pascal without worrying 
about assembly language or hard- 
ware arcana. 

The last of the three levels, 
“Level 2,” extends Level 1 by add- 
ing such niceties such as the au- 
tomatic management of the buf- 
fers on the heap, and a record 
structure for setting the communi- 
cation port options. 

Along with this three-level set 
of basic functions, Turbo Asynch 
Plus contains four other support 
units. One of these units accesses 
the PC’s normal BIOS services 
through interrupt 14H. (This unit 
is probably more useful on a 
PS/2, which has a more complete 
set of communications services, 
including 19,200 baud support, 
built into its BIOS.) The second 
support unit facilitates the process 
of sending commands and receiv- 
ing responses from a Hayes- 
compatible modem. The third unit 
is an XMODEM unit that handles 
the process of transmitting and re- 
ceiving files using XMODEM pro- 
tocol with either checksum or 
CRC. Finally, a text device driver 


allows communications ports to be 
treated as files via the use of 
ReadLn and WriteLn statements. 

Turbo Asynch Plus’ documen- 
tation is good. The three-ring, PC- 
style slipcase binder includes 198 
laser-printed pages and a com- 
plete index. One shortcoming for 
unsophisticated programmers, 
however, is that the fairly techni- 
cal Level 0 functions are discussed 
before the more frequently used 
functions in Levels 1 and 2. For- 
tunately, numerous examples and 
an introductory section on 
asynchronous communications 
soften the blow. All of the exam- 
ple programs are extremely well- 
written and should be no trouble 
to work with. The .DOC files on 
the diskettes also provide addi- 
tional information beyond the 
material in the manual. 

If Turbo Asynch Plus has a 
drawback, it’s that the product’s 
scope is too narrow. In order for 
your program to perform terminal 
emulation, for example, you have 
to write the screen and control se- 
quence handlers yourself. Sim- 
ilarly, the modem support pro- 
vided in the modem unit consists 
simply of sending and receiving 
modem commands with error 
checking, and doesn’t include 
higher-level functions such as ini- 
tialization, dialing, or hangup. 
(You can borrow routines that do 
some of these things from the 
FILEMOVE example program, 
however.) Support for other file- 
transfer protocols, such as Kermit, 
would also be useful. 

But not everyone needs these 
extra functions, and Blaise has 
probably made a wise decision to 
concentrate on the basics of mov- 
ing data over wires. If you need to 
do asynch communications with 
Turbo Pascal—especially over 
multiple lines simultaneously with 
industrial-strength error checking 
and recovery—then Turbo Asynch 
Plus is definitely worth looking 
into. 


— Marty Franz 


TURBO PROFESSIONAL 4.0 
FOR TURBO PASCAL 


TurboPower Software 

P.O. Box 66747 

Scotts Valley, CA 95066-0747 
$99.00 


ou knew it was com- 

ing—as soon as you put 

down your hefty new 

Turbo Pascal 4.0 man- 
ual and your eyes returned back 
to their normal size, you knew that 
software companies would be writ- 
ing some very useful Pascal librar- 
ies in the near future. It was clear 
that the concept of the unit would 
become to software what slots are 
to a motherboard: a third-party in- 
vitation to create enhancements. 
One third-party developer who 
accepted the challenge is Turbo- 
Power Software. 


The manual 
was written by 
someone with a 
clear and concise 
command of the 
English language 
and an obvious 
understanding of 
programming. 


TurboPower’s Turbo Profes- 
sional 4.0 for Turbo Pascal con- 
tains numerous unit files that 
comprise a broad-ranging collec- 
tion of more than 300 Pascal rou- 
tines. These routines support long 
strings (up to 65,520 characters), 
random access text files, interrupt 
service routines, terminate-and- 
stay-resident programming, the 
use of extended and expanded 
memory, runtime error recovery, 
huge arrays (up to 32MB), auto- 
matic heap compression (when 
exiting to DOS or executing a 
child program), sorting, keyboard 
macros, BCD arithmetic, and, of 


course, screen handling. Full 
source code is supplied for all rou- 
tines, including those in assembly 
language. 

It appears that as much time 
was spent documenting Turbo 
Professional as was spent pro- 
gramming it. The spiral-bound 
manual exceeds 400 pages, and 
was written by someone with a 
clear and concise command of the 
English language and an obvious 
understanding of programming 
(this is a rare combination). Each 
chapter of the manual is dedicat- 
ed to one Turbo Professional unit, 
with one or two routines on each 
page. Pascal routines for each unit 
are listed in alphabetical order— 
this is infinitely preferable to a ca- 
nonical alphabetical listing of ev- 
ery routine in one huge section, 
because related routines can be 
found without the need to sift 
through quantities of irrelevant 
material. Each description con- 
tains a subprogram declaration, a 
statement of purpose, comments, 
cross references (“see also...”), 
and—nearly always—an example. 
Frequently, examples of what not 
to do, as well as what to do, are 
presented. Several working exam- 
ple programs demonstrate the use 
of Turbo Professional’s units. Doc- 
umentation also includes a com- 
plete index, plus an appendix that 
contains all unit dependencies. 

Another plus for Turbo Profes- 
sional is its overall approach. Tur- 
boPower did not assume that a 
programmer would buy this tool- 
box for the purpose of building a 
single application around it. As a 
result, most of Turbo Profession- 
al’s routines don’t force a pro- 
grammer to make decisions about 
hardware configurations while 
writing the program. Instead, the 
routines let the program itself 
query the hardware to determine 
the best configuration at runtime. 

As an example, consider Turbo 
Professional’s large arrays. Many 
library products force the pro- 
grammer to determine the size of 
the array at compile time. This ap- 
proach requires a least common 
denominator approach, where the 
array is sized to work on a com- 
puter that has the least amount of 
memory and the least number of 
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hardware features. As long as the 
programmer is writing the pro- 
gram for one person on a known 
computer, this situation is per- 
fectly tolerable. However, it’s not 
tolerable for the person who 
writes general application soft- 
ware where the end user and the 
computer hardware are both un- 
known. Realizing this, Turbo Pro- 
fessional uses pointers and un- 
typed variables to allow each 
routine to manipulate arrays of 
varying sizes. 

In general, any Turbo Profes- 
sional routine can be inserted into 
an existing application without the 
need to restructure the entire ap- 
plication to conform to Turbo Pro- 
fessional. Bravo! 

It’s impossible for a single per- 
son to thoroughly test the more 
than 300 Pascal procedures and 
functions in Turbo Professional. 
However, the routines themselves 
appear to be bug-free—during 
more than six months of use in 
programs ranging in length from 
8000 to 15,000 lines, no bugs man- 
ifested themselves. 

As with all good things, there 
are limits to what can be done 
with Turbo Professional 4.0. The 
screen-handling routines work 
only in text mode. Also, even 
though the manual claims that 
novice programmers with a pass- 
ing knowledge of interrupt service 
routines and terminate-and-stay- 
resident programs can use the 
toolbox for writing TSRs and ISRs, 
there isn’t really enough informa- 
tion in the manual to spare a nov- 
ice some lengthy, and perhaps 
painful, trial and error experi- 
ences in these two areas. In addi- 
tion, nothing indicates how much 
generated code a given Turbo Pro- 
fessional routine adds to your ap- 
plication (a programmer who 
knew the object code size for each 
procedure and function could as- 
sess the tradeoff between the 
power of a routine and the mem- 
ory that the routine uses). Finally, 


Turbo Professional often takes a 
routine that would normally be a 
procedure and makes the routine 
return its own error code by de- 
claring the routine as a function. 
This process often requires the 
use of dummy variable assign- 
ments or do-nothing program 
statements just to call the function, 
as in the following example from 
the manual: 
if not 
SaveWindow(1,1,CurrentWidth, 
Succ(CurrentHeight), 
False,P) 
then 
{can't fail; 
buffer already allocated}; 
These flaws are, at best, quib- 
bles. Turbo Professional 4.0 is a 
well-executed Turbo Pascal tool- 
box with procedures and func- 
tions that are usable by program- 
mers at all experience levels. The 
product is well thought out, rea- 
sonably priced, powerful, and im- 
mediately useful. If you’re looking 
for a good toolbox for Turbo 
Pascal 4.0, I suggest you give Tur- 
bo Professional 4.0 some serious 
consideration. @ 


—Rick Ryall 


386™4* occupies 
only 3K of DOS 


memory, and relo- 
cates the bulk of its 
38K of code to the 
high end of extend- 


ed memory. 


386 MAX 

litas 
8314 Thoreau Drive 
Bethesda, MD 20817-3164 
(301) 469-8848 
$74.95 


ike money, memory isn’t 
everything—but it cer- 
tainly makes many 
things easier. The key in 
either case is to make the most of 
what you have. While the 80386 
CPU contains the machinery for 
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putting memory wherever you 

need it, there’s more to memory 

management than simply throw- 
ing addresses around. Qualitas’ 

386 “* is a utility designed to 

make the most of 386 memory 

management in as many different 
ways as possible. 

386 ““* began as a means to 
fill a hole. The first Intel 386AT 
motherboards had 512K of fast 32- 
bit real-mode RAM, and special 
slots for an additional 4MB of fast 
32-bit extended RAM starting at 
the 1MB mark. However, no alter- 
native existed between 512K and 
640K other than to use slow, 
AT-style 16-bit RAM, which (at 
16mHz) devours machine perfor- 
mance in a torrent of wait states 
the moment program execution 
wanders into it. 386™“** fills that 
128K hole with fast 32-bit extend- 
ed memory, using the 386’s built- 
in memory management. Any 
empty space left in systems with 
MDA or CGA display adapters is 
also filled with DOS memory, up 
to the 704K mark. Furthermore, 
on systems that allow it, 386 ™4* 
fills the empty space between the 
high end of display memory and 
the low end of ROM with 32-bit 
RAM, and makes that RAM avail- 
able to DOS as well. 

These are the obvious tricks 
that can be played with 386 page 
remapping. 386 “* pulls quite a 
few others as well, such as the 
following: 
© 386™4* emulates EMS RAM (in- 

cluding LIM 4.0 functions), us- 

ing 32-bit extended RAM; 

© 386™4* moves slow ROM-based 
BIOS code into fast 32-bit RAM 
(resulting in a 40 percent im- 
provement in BIOS perfor- 
mance); 

® On 16-bit systems equipped 
with 386 accelerator boards, 
386 “4X swaps the slow 16-bit 
RAM on the motherboard with 
fast 32-bit extended RAM on 
the accelerator board; 

e 386™4* can move TSR utilities 
into high DOS memory be- 
tween the display adapter and 
ROM, thus freeing up contig- 
uous low DOS RAM for normal 
applications; 

@ 386™4X can locate blocks of 
ROM, and time memory access 
for all types of memory 
throughout the system. 


In essence, 386 “* is “glue” for 
pulling a system together under 
the 386 and DOS. The product 
consists of a DOS device driver 
that contains the actual memory 
management machinery, plus a 
standalone utility that identifies 
blocks of memory, times memory 
performance, and loads TSRs into 
high memory. The driver occupies 
only 3K of low DOS memory, and 
relocates the bulk of its 58K of 
code to the high end of extended 
memory. 

I’ve successfully used 38 n 
a number of configurations in my 
system, which contains 512K on 
the motherboard and 2MB of fast 
32-bit extended memory. Most fre- 
quently, I backfill the 128K “hole” 
mentioned earlier, and then di- 
vide extended memory into two 
portions. A 1200K section is 
treated as EMS memory that con- 
tains SideKick Plus overlays and 
a Turbo Pascal 5.0 edit buffer, and 
the balance is left as extended 
memory that contains a RAM disk 
for use with the Turbo Pascal com- 
piler and Turbo Assembler. When 
working with graphics, I skip the 
RAM disk and use all of the ex- 
tended memory for EMS, which is 
then divided between SideKick 
Plus and Tall Tree Systems’ JLaser 
SA (Standalone). JLaser SA is a 
small board that allows a bit- 
mapped image stored in EMS 
memory to be converted into vid- 
eo. This video image is fed di- 
rectly to the laser controller of a 
standard Canon-based laser print- 
er. As a result, a full-page 300 dpi 
image prints from memory to 
paper in about 10 seconds. 

The only important limitation 
of 386 “* is due to the nature of 
the 386 itself. 386 “** must be the 
memory management “boss” — 
and other bosses, such as Win- 
dows 386 or PC MOS/386, cannot 
peacefully coexist with 386™“**. For 
the same reason, 386™** conflicts 
with Paradox 386. However, Qual- 
itas and Quarterdeck have coop- 
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erated to allow 386™** to work compiler or assembler will be 

with DESQview as a functional comfortable with the command- 
substitute for Quarterdeck’s own switch complexity of 386 ““*. The 
QEMM memory manager. Qual- product does what it says it will do, 


itas states plainly that ill-behaved and has not failed under my 
TSRs and programs that try to ex- | testing. 


ploit the 386 may conflict with Much of the magic of the 386 
386 “**. In my experience, how- remains dormant because of the 
ever, all important TSRs have lack of software to bring the magic 
functioned correctly, both in low into play. 386 “** turns the magic 
memory and in high memory. loose—I recommend it highly. 
The documentation is terse, but —Jeff Duntemann 


unambiguous and complete. Any 
programmer who has worked suc- 
cessfully with a command-line 


CBTREE, the easiest to use, 
most flexible B+tree file manager 
for fast and reliable record access 


CBTREE... Includes over 8,000 lines of ‘C’ source code FREE! 
Since 1984, thousands of ‘C’ programmers have benefited from using CBTREE. 


Save programming time and effort. You can develop your applications 
quickly and easily since CBTREE'’s interface is so simple. You'll cut weeks off your 
development time. Use part or all of our complete sample programs to get your 
applications going FAST! 

Portable ‘C’ code. The ‘C’ source code can be compiled with all popular C 
compilers for the IBM PC including Microsoft C, Quick C, Turbo C, Lattice C, Aztec 
C and others. Also works under Unix, Xenix, AmigaDos, Ultrix, VAX/CMS, and others. 
CBTREE includes record locking calls for multi-user and network applications. 
The CBTREE object module is only 22K and is easy to link into your programs. 
You don't even pay runtime fees or royalties on your CBTREE applications! 


Reduce costs with system design flexibility. CBTREE allows unre- 
stricted and unlimited designs. Reduce your development costs. You define your 
keys the way you want. Supports any number of keys, variable key lengths, con- 
catenated keys, variable length data records, and data record size. Includes crash 
recovery utilities and more. 


Use the most efficient search techniques. CBTREE is a full function 
implementation of the industry standard B + tree access method, providing the fastest 
keyed file access performance. 
Database Calls: 
© Get first © Get greater than ¢ Insert key 
© Get last © Get greater than or equal ® Insert key and record 
© Get previous © Get sequential block * Delete key 
© Get next © Get partial key match ¢ Delete key and record 
© Get less than © Get all partial matches ¢ Change record location 
© Get less than or equal * Get all keys and locations 


CBTREE is only $159 plus shipping - a money-saving price! 


We provide free telephone support and an unconditional 90-day money back 
guarantee! 

To order or for additional information on any of our products, call TOLL FREE 
1-800-346-8038 or (703) 847-1743 or write using the address below 


NEW CBTREE add-on products to make your programming easier. AVAILABLE 
NOW! « Adhoc query, reporting system; ¢ SQL interpreter 


If you program in ‘C’, sooner or later you're going to need a B+tree. Don't delay until you're 
in a crunch, plan ahead, place your order for CBTREE now. Orders shipped within 24 hours! 


PEACOCK SYSTEMS, INC. 
ArwN 2108-C GALLOWS ROAD 
Vir EN VIENNA, VA 22180 


PEACOCK SYSTEMS, INC 
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BOOKCASE 


C PROGRAMMER’S GUIDE TO 
SERIAL COMMUNICATIONS 


Joe Campbell, Howard W. Sams & 
Company, Indianapolis, IN: 1987, 
ISBN 0-672-22584-0, 670 pages, soft- 
cover, $22.95, diskettes (2) $35.00, 
ASCII wall chart $10.00. 


hether you're a com- 

puter communica- 

tions user or a pro- 

grammer, if you 
want to learn more about com- 
puter communications, then this 
book is required reading. It’s 
really two books in one: An intro- 
duction to serial communications, 
and a communications guide for 
C programmers. 

The first of the book’s two sec- 
tions covers the basic topics that 
you need to understand before 
you attempt any serious serial 
communications programming. 
This introductory and background 
material, although somewhat tech- 
nical, is clearly written and inde- 
pendent of any programming lan- 
guage. The discussion concen- 
trates on defining serial communi- 
cations, describing how it works, 
and providing insight as to why it 
often appears to be such an ar- 
cane field. This section contains 
no program code at all. 

The second section gets down 
to the business of programming 
serial ports in C (along with a little 
help from assembly language), 
and includes program listings for 
IBM PC and Kaypro computers. 
The C code is standard enough to 
be widely applicable across hard- 
ware environments and C compil- 
ers. The ubiquitous Hayes modem 
(and compatible modems) is pre- 
sented as the basis of the program 
interface to data communications 
hardware. 


HOWARD W. SAMS & COMPANY 


C Programmer's 


Guide to Serial 
Communications 


Joc Campbell 


If you are not already a moder- 
ately experienced C programmer, 
you're apt to have trouble with the 
material in this section. The au- 
thor advises relative newcomers to 
C to gain appropriate experience 
first, and then come back to the 
book—this is good advice. 


COVERAGE 


As the title states, the book’s cov- 
erage is limited to serial communi- 
cations, and further restricted to 
the asynchronous realm. Even 
those restrictions leave a lot of 
ground to cover. 

Campbell presents an entertain- 
ing history lesson on the evolu- 
tion of serial communications 
since the late 1800s. Although 
short in human terms, the history 
of communications is a lengthy 
one in the technological sense, 
and it’s interesting to see the ef- 
fect of the legacy of mechanical 
contrivances upon today’s solid- 
state technology and terminology. 
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An examination of standards 
describes and explains the ASCII 
character set, including the codes 
that represent letters, numbers, 
punctuation marks, and control 
characters. The EIA RS-232 serial 
specification—the electrical, me- 
chanical, and functional specifi- 
cation to which our computer’s se- 
rial ports and modems should 
adhere—is discussed as well. 

The author categorizes ASCII 
characters into six sets: graphics 
characters; physical device con- 
trol; logical communications con- 
trol; physical communications 
control; information separators; 
and code extension controls. 
Characters in each category are 
fully described and clearly ex- 
plained. Extensive use of tables 
and illustrations helps clarify and 
organize this standards informa- 
tion, which is far more accessible 
than it is in any of the standards 
documents themselves. 

Campbell takes the time to ex- 
plain the many conventions of se- 
rial communications, such as the 
uses of control codes. His book is 
one of only a small number of 
books that accurately define the 
BREAK signal and its purpose, 
and delve into the inner workings 
of the cyclical-redundancy check 
(CRC) method of error detection. 

In his description of the infa- 
mous RS-232-C standard and its 
application, Campbell is careful to 
point out how the interface is reli- 
able for its intended purpose, 
which is to connect data terminal 
equipment (DTE), such as termi- 
nals and computers, to data com- 
munication equipment (DCE), 
such as modems. The fog that sur- 
rounds the RS-232-C has been the 
result of poorly written standards 


documents, and the frequent ap- 
plication of the standards to situa- 
tions far outside of their intended 
scope. 

With all of the current interest 
in public-access bulletin-board sys- 
tems and information utilities, file 
transfer protocols are a hot topic. 
Campbell presents technical and 
operational aspects of the Kermit 
and XMODEM file transfer pro- 
tocols to show how both binary 
and ASCII text files can be easily 
moved from one computer system 
to another. 

The subject of error detection 
and correction is an important 
one, and Campbell gives it a sig- 
nificant amount of coverage. He 
describes the use of simple parity, 
checksums, and CRC methods to 
detect errors. 

Campbell approaches the uni- 
versal asynchronous receiver/ 
transmitter (UART)—the heart of 
the computer’s serial port—from 
two directions. He first describes 
a virtual UART, which demon- 
strates all of the tasks that a UART 
must do in order to convert paral- 
lel data to an asynchronous serial 
form and vice versa. (These tasks 
are not trivial because of exacting 
timing considerations and other 
factors.) The process of designing 
a virtual UART helps program- 
mers appreciate the benefits of us- 
ing a packaged UART, and gives 
them an understanding of the 
complex programming require- 
ments of a general-purpose UART 
such as the National 8250. 

The final chapter of the book 
describes interrupts in the IBM 
PC family of computers and the 
Kaypro machine. This material 
shows how to implement inter- 
rupt-driven, rather than polled, 
communications programs. The 
inclusion of the Kaypro informa- 
tion provides an important com- 
parison of serial communications 
in both the DOS and CP/M oper- 
ating system environments. Be- 
cause the Kaypro has no internal 
timing facilities, the programmer 
faces a much more difficult task in 
generating precise timing inter- 
vals, delays, and “tick” marks. The 
relatively small amount of assem- 
bly language code in this book is 
confined to low-level tasks such as 
timing functions, checking key- 
board status, and other hardware- 
dependent functions. 


STRENGTHS AND 
WEAKNESSES 


The C Programmer’s Guide to Serial 
Communications provides excellent, 
in-depth coverage of crucial topics 
of serial communications pro- 
gramming that are often neg- 
lected. This very readable book is 
a good blend of theory and prac- 
tice, and is carefully crafted. 
Physically, the book is both too 
big and too small. I would prefer 
to see this 650-page book divided 
into two separate volumes—each 
of the two sections is effectively a 
complete book in itself. (Well, al- 


most—the second book could dis- 
cuss such additional topics as 
background communications and 
RS-232 networks.) 

Diskettes of source code are 
available from the author. The 
source requires the use of an as- 
sembler in addition to a C com- 
piler. Some minor modifications 
to the C and assembler source 
files are needed in order for these 
files to work with certain compiler 
and memory-model combinations. 
Appendix C contains instructions 


continued on page 156 


i i eb 


Realize The 
Hidden Potential 
In Your 386! 


Imagine more fast memory to run CAD/CAM spread- 
sheets, networks and other memory-hungry applications. 
386MAX™ takes advantage of the unique memory remap- 
ping capabilities of the 80386 chip maximizing the speed and 


memory management potential of your 386. 


Additional Memory 

@ Opens up more DOS memory for 
applications by moving memory 
resident programs—including 


most network files—to “High DOS” 


memory above 640K. 
@ A typical system with an EGA 
would have 176K High DOS avail- 


able (less 64K for full EMS support). 


Speed 

m Makes 386 accelerator boards 
run at their fastest speed by 
swapping fast 32-bit memory 
into first 640K. 

@ Speeds up EGA display by 40%. 
Automatically remaps slow system 
and EGA ROMs into fast RAM. 


System requirements: 


Any 80386-based PC witha minimum ga 


Ge QUALITAS® 


of 256K extended memory. Needs 
4KB to install in CONFIG.SYS. Sup- 
ports up to 32 MB of EMS memory. 


EMS Support 

@ Converts all or part of your 
extended memory to expanded 
memory fully emulating LIM 4.0. 

@ Provides the EMS memory 
management support needed for 
multitasking programs (Windows 
2.03, etc.). 

386 Utilities 

= Displays memory speed 

= Maps resident program usage 
including high DOS memory 

# Displays EMS memory usage 

= Scans for ROM addresses 


$74.95 iar aeker longa shipping, 


To order 386MAX\™" call: 
301-469-8848 


8314 Thoreau Drive Bethesda, Md 20817 FAX 301-469-5810 
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BOOKCASE 
continued from page 155 


to help you with the assembly lan- 
guage interface under PC-DOS/ 
MS-DOS. 

Joe Campbell’s C Programmer's 
Guide to Serial Communications has 
taken a position on my reference 
shelf next to the dictionary, the- 
saurus, C compiler manuals, and 
other frequently used reference 
volumes that must be within three 
feet of my operating position. 

Campbell calls serial communi- 
cations programming “doing bat- 
tle with the serial port’—this is an 
apt description of the process to 
those of us who have done it. This 
book gives you the tools and tech- 
niques that you need to have a 
fighting chance in that battle—a 
programmer who wanders off into 
serial communications without 
this handy guidebook is taking in- 
ordinately high risks. @ 

— Reid Collins 


FILE FORMATS FOR 
POPULAR PC SOFTWARE 


Jeff Walden, John Wiley & Sons, Inc., 
New York, NY: 1986, ISBN 0-471- 
83671-0, 287 pages, softcover, 
$24.95. 


MORE FILE FORMATS FOR 
POPULAR PC SOFTWARE 


Jeff Walden, John Wiley & Sons, Inc., 
New York, NY: 1987, ISBN 0-471- 
85077-2, 369 pages, softcover, 
$24.95, 


s one who has written 
books, I sometimes re- 
view books with a bit of 
envy, wishing that I had 
been given the contract instead, 
and wondering how I could have 
made the book better. But the 
writing of these two books is a job 
I wouldn’t wish for. File Formats for 
Popular PC Software and More File 
Formats for Popular PC Software 
present file formats that are used 
by popular PC application pro- 
grams. This is hardly a subject to 
stir the blood, but it’s required 
reading for anyone who programs 
a PC for a living. 
Each spiral-bound book has 
sturdy, glossy stock covers. With 
each book you get very little 


FILE 
FORMATS 


FOR POPULAR PC SOFTWARE 
A PROGRAMMER’S REFERENCE 


Jeff Walden 


snappy patter, no tutorial informa- 
tion, and three parts. The first 
part of each volume describes 
each file format in excruciating 
detail. No-nonsense tables present 
information about byte offsets, 
contents, and their purpose. While 
a few comments have been added, 
explanations are kept to a min- 
imum. A notable exception is the 
Framework II format that is pre- 
sented in More File Formats—with 
63 pages of description, it’s easily 
the most complicated file de- 
scribed in either of the two books. 
The second section of each book 
contains dumps of sample files 
with expanded control characters 
and added offsets (presented in 
what author Jeff Walden terms 
“music staff’ style). The final part 
of each volume consists of the 
source listing of the Turbo Pascal 
program that produced the 
dumps. 

The first book contains the file 
formats for Lotus 1-2-3, Sym- 
phony, Ability, dBASE II and III, 
DIF, Multimate, Microsoft Multi- 
plan (SYLK), SuperCalc 3, Visi- 
Calc, WordStar, and WordStar 
2000. The second book contains 
formats for Framework II, Reflex, 
Microsoft Rich Text Format, 
SuperCalc 4, SuperProject Plus, 
Volkswriter, and WordPerfect. 
Most of the formats were obtained 
with the direct cooperation of the 
various vendors, so the informa- 
tion can be assumed to be accu- 
rate. The author scrupulously 
identifies the versions of the soft- 
ware that correspond to the file 
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formats described in the text. As 
new versions of software are re- 
leased, we can only hope that 
these books will keep up with the 
leading edge. 

The value of this file format in- 
formation cannot be overstated. 
Just glancing at the layout for Lo- 
tus 1-2-3 .WKS files, for example, 
is enough to convince me that 
there’s no way I'd reverse-engi- 
neer it even if I had a river of Jolt 
Cola and the fastest 386 system my 
employer could buy. But thanks to 
Mr. Walden’s efforts and Lotus’ 
cooperation, the necessary infor- 
mation is all there in the book. Al- 
though the fiendishly intricate 
structure of the .WKS files re- 
quires fancy coding in order to 
create a routine to read or write 
Lotus files, you now have a fight- 
ing chance. 

Not only is the information in 
these books valuable, it’s useful in 
a practical sense. If you develop 
software programs for a large cor- 
poration that uses one or more of 
the programs discussed by Mr. 
Walden, you will need to read or 
write at least one of these files 
eventually. While most major ap- 
plications perform ASCII file 
translation, the ability to read and 
write files in the files’ native for- 
mat offers a cleaner and more di- 
rect way to interface to those files. 
In addition, some programs, such 
as WordPerfect, support more fea- 
tures in native file format than in 
ASCII format, so direct access be- 
comes a requirement. 

In short, since the ability to ex- 
change data between applications 
is an important consideration of 
PC programming these days, the 
file layout information provided 
in these two books is a necessity. 
But don’t plan on buying these 
books, reading them just once, 
and then coming away from the 
experience with detailed knowl- 
edge about the internal workings 
of the covered products. These 
are reference books—you will 
need knowledge of both a specific 
application and a programming 
language in order to make good 
use of the books’ information. 
While programming to proprietary 
file formats isn’t easy, Mr. 
Walden’s two indispensable books 
make it at least possible. 


—Marty Franz 


TURBO RESOURCES 


COMPUSERVE 


The best online information about 
the Borland languages can be found 
on CompuServe’s three Borland fo- 
rums. Quite apart from providing 
the listings appearing in TURBO 
TECHNIK, the Borland forums con- 
tain many megabytes of useful util- 
ities and source code in all Borland 
languages. Furthermore, some of the 
most interesting and knowledgeable 
people in the programming subcul- 
ture hang out on CompuServe, pro- 
viding an informal, online user 
group that is always in session. If 
you have a question, leave a mes- 
sage in the appropriate forum, and 
in almost every case someone will 
jump in with an answer. 

Subscribing to CompuServe can 
be done through the coupon en- 
closed with every Borland product 
(which also includes $15 worth of 
online time for your first month) or 
by calling CompuServe at (800) 848- 
8199. You'll need a modem and 
some sort of communications soft- 
ware that supports the XMODEM 
file transfer protocol. 


How to access the Borland 
Forums on CompuServe: 


TURBO TECHNIX listings for Turbo 
Pascal and Turbo Basic are available 
in Library 1 of the BPROGA 
Borland ming Forum (GO 
BPROGA). Turbo C, Turbo Prolog, 
and Turbo Assembler listings are 
stored in Library 1 of the BPROGB 
Forum (GO BPROGB). Listings for 
Business Language articles are also 
available in Library 1 of the Borland 
Applications Forum (GO BORAPP). 
From the initial CompuServe 
prompt, type GO <forum name> or 
follow the menus. If you’re not al- 
ready a member of a forum, you 
must join by following the menus 
before you can download the 

listing files. 


How to download TURBO 
TECHNIX code listings from 
CompuServe: 


At the forum menu, type: Library 1. 
This will take you to the TURBO 
TECHNIX data library, where all list- 
ing files are stored. Listing files are 
archived using the ARC52 archiving 
scheme. You will need the 
ARC-E.COM program (available in 
Library 0 of BPROGA, BPROGB, 
and BORAPP) or one compatible 
with it to extract listing files from 
downloaded archives. 

Magazine archive files are organ- 
ized two ways: by article and by 
issue. In other words, there will be 
one .ARC file for every article that 
includes listings; and a single, larger 
-ARC file for each issue that con- 
tains all of the individual .ARC files 
for that issue. You can therefore 
download listings for individual ar- 
ticles, or download the entire issue’s 
listings in one operation. 

The all-issue files follow a naming 
convention such that NVDC87.ARC 
contains all listing archives from the 
November/December, 1987 issue, 
JNFB88.ARC contains the listings 
from the January/February, 1988 
issue, and so on. The name of an ar- 
ticle’s individual listings archive file 
is given at the end of the article. 

To download an archive file, bring 
up the Library 1 prompt and type: 
DOW <filename>/PROTO: XMO 


After pressing Enter, start your own 
communications program’s XMO- 
DEM receive function. After you 
have completely received the file, 
you must press Enter once to inform 
CompuServe that the download has 
been completed. Once you have 
downloaded an archive file, you can 
“extract” its component files by in- 
voking ARC-E.COM at the DOS 
prompt with: 


C>ARC-E <filename> @ 


CHANGE OF ADDRESS 

If you’ve moved or changed your 
name since you began receiving 
TURBO TECHNIX, please let us know 
so we can make sure your copies go 
to the right person in the right place. 
Send us a letter providing both your 
old and your new name and address, 
and attach an existing mailing label 
from TURBO TECHNIX if possible. 
Send the letter to: 


TURBO TECHNIX 

Attn: Magazine Dept., Subscriptions 
Borland International, Inc. 

1800 Green Hills Road 

Scotts Valley, CA 95066-0001 


ONLINE AND 
BETWEEN COVERS 


The following information describes 
two sources where you can learn 
more about Borland language prod- 
ucts: On the Borland CompuServe fo- 
rums, and in books now or soon to be 
in print. This issue, the CompuServe 
highlights are from the Turbo Pascal/ 
Turbo Basic Forum, BPROGA. The 
files shown in this section are not re- 
lated to articles in TURBO TECHNIX, 
but are of general interest to Turbo 
programmers. All files for Turbo Basic 
are stored in Library 9; all Turbo 
Pascal files are stored in Library 2. 
The books presented here are only a 
sampling. (We can’t possibly list all 
published Borland-related books. 
Also, this listing reflects no judgment 
about the quality of any book.) For 
more information on these and other 
Borland-related books, contact the 
publishers or your local bookstore. 


TURBO PASCAL: (Library 2) 


PIBMDO.ARC _ Uploaded: 6/6/88 
Size: 20,935 bytes 

This archive contains routines for in- 
terfacing Turbo Pascal 4.0 programs 
to several popular DOS-based multi- 
taskers: TaskView, OmniView, DESQ- 
view, DoubleDos, and TopView. 


continued on page 158 
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TURBO RESOURCES 
continued from page 157 


DESQ10.ARC 
Size: 6,794 bytes 
DESQview interface routines recom- 
mended and published by Quarter- 
deck to create DESQview-aware pro- 
grams and adapted for use with Turbo 
Pascal 4.0. Complete assembler and 
Pascal source files included. Routines 
permit direct writing to video buffers 
with utilities such as QWIK41A.ARC. 


TPHRT.ARC Uploaded: 6/2/88 
Size: 10,112 bytes 

TPHRT is a high-resolution timer/ 
profiler for Turbo Pascal 4.0. The user 
places simple calls to TPHRT routines 
in the source code under study, com- 
piles and runs the code, and a com- 
plete report of all TPHRT timer activ- 
ity is generated. Up to 100 different 
timers may be active. Resolution is 
one microsecond and is self-cali- 
brating. 
EGASAV.ARC 
Size: 3,072 bytes 
This archive contains a unit that in- 
terfaces two routines for saving and 
restoring EGA (640 X 350) 16-color 
graphics screens to and from RAM. 
Provides a good example of accessing 
and programming the EGA’s internal 
registers. 


AUTOI2.ARC 
Size: 3,840 bytes 
This program illustrates how to 
change the values of typed constants 
within a Turbo Pascal .EXE file. This 
is a common technique that can be 
used to create installable software. 


STDERR.ARC Uploaded: 3/15/88 
Size: 1,662 bytes 

This unit provides access to the stan- 
dard error device through a prede- 
fined text file variable. Version 1.1 
fixes the problem with command-line 
redirection to a file. 


Uploaded: 6/6/88 


Uploaded: 5/5/88 


Uploaded: 4/26/88 


TURBO BASIC: (Library 9) 


BASICA.UNP _ Uploaded: 4/30/88 
Size: 1,212 bytes 

This program demonstrates how to 
unprotect a program saved in Inter- 
preted Basic (BASICA or BW-Basic 
with the /P option) so you may load 

it into Turbo Basic and compile it. 


DATASC.ARC Uploaded: 9/10/87 
Size: 4,224 bytes 

Datascrn is a free-form screen- 
oriented numeric data input routine. 
It’s intended for use in calculation in- 
tensive programs that require multiple 
numeric input variables that can be 
revised quickly and easily. Datascrn is 
readily incorporated into the main 


program as an include file. Data 
screens are designed and saved 
separately. 


NWDMO2.ARC_ Uploaded: 5/30/88 
Size: 7,964 bytes 

Latest demo in source code of window 
effects that can be created with the 
help of either the Turbo Basic Editor 
Toolbox or the Turbo Basic Database 
Toolbox. You must have either the Ed- 
itor Toolbox or the Database Toolbox 
to compile this demo, because the ac- 
tual screen routines are in two Tool- 
box routines. If you do not have the 
Toolboxes, see the file WOEMO.ARC 
for the .EXE file. 


WDMO2.ARC 
Size: 40,495 bytes 
WDMO02 demonstrates some window- 
ing capabilities of the Turbo Basic 
Toolboxes. This .EXE file demon- 
strates the windowing capabilities of 
a Toolbox for those who don’t own 
one. The source code is in the file 
NWDMO2.ARC for the additional 
routines that call the Toolbox 
routines. 


VARSTR.ARC 
Size: 1,408 bytes 
This file demonstrates how you can 
find the address at which Turbo Basic 
has stored your strings. 


CPI.ARC Uploaded 4/5/88 
Size: 19,072 bytes 

CPI (Communication Program Inter- 
face) is a TSR device driver for buf- 
fered data input, baud-rate selection 
from 75 to 115,200 baud, background 
communication, signing on data in- 
put, and more. Easy to use with any 
language or direct from DOS without 
programming the comm chip. 


Uploaded: 5/30/88 


Uploaded 4/6/88 


TURBO C BOOKS 


Turbo C for Beginners; Steve Burnap; 
Compute! Books 

Turbo C, The Essentials of Programming; 
Ira Pohl/AI Kelly; Benjamin/ 
Cummings 

Using Turbo C; Herbert Schildt; 
Osborne/McGraw-Hill 

Advanced Turbo C; Herbert Schildt; 
Osborne/McGraw-Hill 

Turbo C: Memory Resident Utilities, 
Screen I/O and Programming Techniques; 
Al Stephens; MIS Press 

Turbo C, The Art of Program Design, 
Optimization and Debugging; Stephen 
Randy Davis; M&T Books 

Turbo C Programmer’s Library; Kris 
Jamsa; Osborne/McGraw-Hill 

Turbo C: The Complete Reference; Ste- 
phen O’Brien; Osborne/McGraw-Hill 
The Waite Group’s Turbo C Bible; Naba 
Barkabati; Howard W. Sams & Co. 
Turbo C Programming for the IBM; 
Robert LaFore; Howard W. Sams & Co. 
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Complete Turbo C; Strawberry Software; 
Scott, Foresman & Co. 


Programming with Turbo C; Beverly 
and Scott Zimmerman; Scott, Fores- 
man & Co. 


Mastering Turbo C; Stan Kelly-Bootle; 
Sybex Inc. 

Systems Programming in Turbo C; 
Michael Young; Sybex Inc. 

Turbo C Programmer’s Guide; Nathan 
Goldenthal; Weber Systems, Inc. 


Turbo C Programmer’s Resource Book; 
Frederick Hultz; Tab Books, Inc. 


Turbo C DOS Utilities; Robert Alonso; 
John Wiley & Sons, Inc. 


Turbo C Survival Guide; Larry Miller/ 
Alex Quilici; John Wiley & Sons, Inc. 


Turbo C Programmer's Guide; B. 
Barden; John Wiley & Sons, Inc. 


Turbo C At Any Speed; Richard Wiener; 
John Wiley & Sons, Inc. 


TUG 


The national user group for Turbo 
languages is TUG, the Turbo User 
Group. TUG publishes a bimonthly 
journal called Tug Lines that contains 
bug reports, programming how-to’s, 
and product reviews. Extensive public- 
domain utility and source code librar- 
ies are available to members. An op- 
tional multi-user BBS with file upload- 
ing/downloading, messaging, and 
teleconferencing is available to the 
public. Membership dues are $24.00 
US/year (including Washington 
State); $28.00 Canada and Mexico; 
$39.00 overseas. 


TUG 

P.O. Box 1510 
Poulsbo, WA 98370 
BBS: (206) 697-1151 


LOCAL USER GROUPS 


One of the best places to look for ad- 
vice and face-to-face assistance with 
your programming problems is at a lo- 
cal user group meeting. Most user 
groups in the larger cities have special 
interest groups (SIGs) devoted to the 
most popular programming lan- 
guages, usually with strong Turbo 
presences. We will be listing some of 
the largest and most active user 
groups in major urban areas across 
the country; obviously, there are thou- 
sands of user groups that we cannot 
list due to space limitations. If no 
listed group is convenient to you, ask 
about local user groups at a local com- 
puter store or check with a faculty 
member at a high school or college 
with a computer curriculum. 


BOSTON COMPUTER SOCIETY 
Information: (617) 367-8080 
BBS: (617) 227-7986 
One Center Plaza 
Boston, MA 02108 


CAPITAL PC USER GROUP (DC) 
4520 East-West Highway, Suite 550 
Bethesda, MD 20814 


CHICAGO COMPUTER SOCIETY 
Information: (312) 794-7737 
BBS: (312) 942-0706 
P.O. Box 8681 
Chicago, IL 60680-8681 


HAL/PC (HOUSTON) 
Information: (713) 524-8383 
BBS: (713) 847-3200 or 
(713) 442-6704 


NEW YORK PC USER GROUP, INC. 
Information: (212) 533-6972 
BBS: (212) 697-1809 
40 Wall Street, Suite 2124 
New York, NY 10005 


PACS (PHILADELPHIA) 
Information: (215) 951-1255 
BBS: (215) 951-1863 
PACS, c/o Lasalle University 
Philadelphia, PA 19141 


SAN FRANCISCO PC USERS GROUP 
Information: (415) 221-9166 
BBS: (415) 621-2609 
3145 Geary Blvd, Suite 155 
San Francisco, CA 94118-3316 


ST. LOUIS USERS GROUP 
Information: (314) 968-0992 
BBS: (314) 361-8662 

TWIN CITIES PC USER GROUP 
Information: (612) 888-0557 
BBS: (612) 888-0468 


P.O. Box 3163 

Minneapolis, MN 55403 
ADVERTISERS’ INDEX 
Advertiser Page No. 
Aker Corp. 115 
American Cybernetics 43 
ASCII 159 
Austin Code Works, The 47 
Black & White International 37 
Blaise Computing 5 
Borland International, Inc. 29-32, 


44-45, 89, 93, 97, 109, 116-117, 131-135 


Burgiss Group, The 127 
Chen & Associates, Inc. 159 
CHANCElogic 51 
Computer Solutions 159 
Disk Software 36 
English Knowledge Systems, Inc. 159 
Entelekon Software Systems 61 
Ithaca Street Software, Inc. 159 
Lahey Computer Systems, Inc. 39 
Matrix Software 25 
Max Software Consultants, Inc. 147 
Microway 41 
Nostradamus 23, C3 


C:>CLASS.ADS 


C:>CLASS.ADS is TURBO TECH- 
NIX magazine’s display classified 
advertising section. Special sizes 
and rates are available for 
C:>CLASS.ADS—$150 per column 
inch, with a 2-inch minimum. (A 
minimum ad, for example, mea- 
sures exactly 2 '/16” wide by 2” 
long.) All C:>CLASS.ADS must be 
prepaid and submitted in camera- 
ready form (black and white PMT 
or Velox) to: 


C:>CLASS.ADS 

TURBO TECHNIX 

1800 Green Hills Road 

P.O. Box 660001 

Scotts Valley, CA 95066-0001 
For information, please contact the 


Advertising Department at (408) 
438-9321. 


T Pascal, Turbo C 
Microsoft C 
Complete data base 
code in just 10 minutes! 
Draw & paint your screens, point out indexes & 
that’s it! Generator has: B-tree file manager, 
Automatic indexing, Context sensitive help, 


Automatic programmer documentation. 
Unlimited technical support 


T Pascal $389 / C Versions: $499 


30 day money-back guarantee 


Turbo Programmer 
ASCII - (800) 227-7681 


Opt-Tech Data Processing 


Osborne/McGraw-Hill 

Paradigm Systems 123 
Peacock Systems 153 
Perpetual Data Systems 40 
Polytron Corporation 85 
Programmer’s Connection 9 
Programmer’s Connection/ 

Blaise Computing 7 
Programmer’s Paradise 112 
Qualitas, Inc. 155 
Quarterdeck Office Systems C2-1 
Research Group, The 15 
Software Artistry 11 
Softway, Inc. 50 
Sophisticated Software 35 
TOP GUN Systems 18-19 
Trio Systems 69 
TurboPower Software 46 
Vertical Horizons Software 65 
Visitech Software 22 
Zenreich Systems 127 


PASCAL»C 


& Convert Turbo Pascal (V3.X) to Turbo C! 
4 Saves You Hundreds of Hours! 
& $99 + S&H (US/Canada=$5, Foreign=$20) 


& Foreign Bank Check, add $30 
P.O./C.0.D., add $10 


4 Demo Disk = $5 


CHEN & ASSOCIATES, INC. 
4884 Constitution Ave., Ste. 1E 
Baton Rouge, Louisiana 70808 


(504) 928-5765 (inquiries) / 1-800-448-CHEN (Orders) 


TURBO SOFTWARE 


We have a large collection of the best Shareware & 
Public Domain for the Turbo Languages! 
Turbo Pascal3.0 6 disks for $25 
4.0 4 disks for $18 
Turbo Prolog 3 disks for $14 
Turbo C 5 disks for $21 
Turbo Basic 3 disks for $14 
3 1/2 disk format $1 per disk extra. 
All disks completely filledl| Windowing Packages, Utilities, Ex- 
amples, Tutorials, Enhancements, and more, Free 32 pg. cata- 
loge with over 200 disks described. Each disk only $4.50 or less. 
Free shipping! Visa/Master Card, C.0.D. 


Computer Solutions 
P.O. Box 354 + Mason, MI 48854 
1-800-874-9375 to order 
1-517-628-2943 for info & MI 


JAKE™: A BREAKTHROUGH IN 
NATURAL LANGUAGE SOFTWARE 


Create a natural language front end to your 
database, game, or graphics program! JAKE 
is a library usable with Turbo C for translating 
English queries and commands into function 
calls and data structures. JAKE offers context- 
sensitive semantic processing, while interfacing 
easily to any application and using <64K 
of memory. $495 complete. 

Sound too good to be true? Get our 
interactive demo for only $10 and see. 

CALL (408) 438-6922 VISA, MC 
Em English Knowledge Systems, Inc. 
its 5525 Scotts Valley Dr. Suite 22 

Scotts Valley, CA 95066 


OptT-TECH SorT™ 


The High Performance Sort/ 
Merge utility. Use stand-alone or 
Call as a subroutine. Unlimited 
filesize, multiple keys, record 
selection & much more! 


for MS-DOS $149. 
Call or write for more info. 


Opt-Tech Data Processing 
P.O. Box 678/Zephyr Cove, NV 89448 


(702) 588-3737 


ICON-TOOLS'™™ 


Icon editor, icon files, 
C function source code. 
Turbo C, Quick C, MetaWIND, 
ESI, and GFX graphics. 


$69.95 


Ithaca Street Sof tware,Inc. 
1 Ithaca Drive 
Boulder, CO 80303 


(303) 494-8865 
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PHILIPPE’S 
TURBO TALK 


With Turbo Debugger, 


cademic types will tell 

you that with proper de- 

sign techniques, it’s pos- 

sible to write programs 
that are correct from the word 
GO. In the real world, with real 
programs that do real work, it 
never works out that way. In fact, 
if a program under development 
never crashes, it can’t be much of 
a program! 

Even the best jugglers drop 
some balls when they work on 
new tricks! As a matter of fact, it 
is well known that the best 
jugglers are probably the ones 
that have dropped a lot of balls. 
There’s nothing wrong with crash- 
ing during development. What’s 
wrong is crashing and not under- 
standing why. 


ERROR IS HUMAN, BUT... 


In 44 B.C. (Before Computers), 
Cicero said: “Any man can make 
mistakes, but only an idiot persists 
in his error.” In Latin, it became 
more radical over time: “Erare 
humanum est, sed perseverare diabol- 
icum: Error is human, but repeat- 
ing it is an act of the devil!” 

Of course, you have to spend 
time and energy in careful soft- 
ware design, or the product will 
never even be finished, much less 
work. The primary factor is the 
project’s overall architecture. 
That’s the foundation on which 
work will be done. It has to be 
solid and very well thought out. 
Then you start with a design, and 
I guarantee you that there will be 
some major changes to that de- 


it’s OK to crash! 


Philippe Kahn 


sign by the time the product ships. 
It’s natural. Otherwise, you can 
bet that it won’t be much of a 
product. Too many people show 
more interest in a quick profit 
than in quality work. Products are 
rushed to market even though the 
programs have more bugs than a 
tropical island. 

But even with the best design 
humanly possible, there will be 
bugs. There will be crashes. The 
key is to have good people using 
debugging tools that they under- 
stand, so that even the worst crash 
is a learning experience. 


THE RIGHT TOOLS 


Your tools should match your 
problem. You can’t debug a 
leading-edge program with a 
trailing-edge debugger. If you’re 
going to program for the 386, your 
debugger had better understand 
the 386. If your program is going 
to use EMS, your debugger had 
better understand EMS. Other- 
wise, you're over-driving your 
headlights ... 

Turbo Debugger helps you to 
see what’s going on. Look at every- 
thing. If your program brings the 
system down, look carefully at all 
the side effects as well. That can 
be quite an education right there: 
You can learn more about DOS 
when it goes down in flames than 
you can when it works! But you 
don’t learn anything unless you 
can watch what happens right up 
to the explosion. 

It helps to have a safe place to 
watch from. Powering down is a 
waste of time. That’s why at 
Borland we built 386 support into 
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Turbo Debugger. We put Turbo 
Debugger in one protected virtual- 
86 partition and left the test pro- 
gram in another, so that even if 
the test program crashes its par- 
tition, nothing touches Turbo 
Debugger. 

And then there are the danger- 
ous ideas you get while imple- 
menting a cutting-edge design. 
They may work fine, or they may 
blow you away every time, but you 
won’t know until you try, and with 
Turbo Debugger you can make an 
informed decision. Without Turbo 
Debugger, you can only do what’s 
safe. With Turbo Debugger, you 
can explore new territory and 
make it safe. 


WATCH WHAT GOES WRONG 


This is the importance of debug- 
ging: To watch what goes wrong 
so that you can not only fix that 
bug but recognize that whole class 
of bugs. Little by little, you fine- 
tune your design so that it be- 
comes crashproof. 

It’s OK to crash. A program can 
die a thousand deaths, and come 
back every time. And each time 
it'll be a little better, if you really 
work at learning from your mis- 
takes. Remember, someone who 
never makes a mistake doesn’t 
usually make anything, and like 
the ancient Chinese saying goes: 
“The first thousand times don’t 
count!” 


Tur Oo-Plu S 5. 


» Assembler ciency 
« I/O Code Generation 
- Window Code Generation 
_ Window Management 
= Special Effects 
» Screen Support 
= System Integration 
« User Color Selection 
© Run-Time Dynamic Menus 
« Universal Menus 
© Window & Menu Compression 
© Transparents and Shadows 
= Keyboard Support 
= Cursor Support 
« Field I/O Routines 
« Reentrant Routines 
= Diagnostic Tools 
= File Handling 
= System Resources 
= Sound Effects 
= Critical Error Handlers 
= Automatic Directories 
= Sample Programs 
= Complete Pop-Up Help 
= 280 Page Iilustrated Manual 


Nostradamus Inc. 

3191 South Valley Street (Suite 252) 
Salt Lake City, Utah 84109 

(801) 487-9662 

Data/BBS 801-487-9715 1200/2400,n,8,1 


Visa, Amex, C.0.D., Check or P.O. 

60-day satisfaction, money-back guarantee 
Demo Diskettes and brochures available 

Out of U.S. add postage 


Nasirananis 


The Language Standard is TURBO PASCAL 4.0 
The Enhancement Standard is TURBO PLUS 5.0 


“Turbo Plus 5.0 gives every Program thé 
professional touch. . . saves hours of coding. 
A must in my programming.” 


Mike Cushman « Former Editor, “*.*,” PC World 


“After spending hundreds upon hundreds of dollars searching 
through many utilities and libraries, I must say that 
Nostradamus is my choice!” 


Mr. Paul Mayer * ZPAY Payroll ian * Franklin Park, IL 


“I’ve tried most similar products on the market, Turbo-Plus with Screen 
Gente is clearly superior.” 


Dr. David Williamson « Chiropractic Health Services * Durnam, NC 


“This ts, without a doubt, the most powerful and easy to use programming toolbox that 
I have seen for the PC environment, and Turbo Pascal in particular.” 


Mr. John Drabik + Geotron International, Inc. * Salt Lake City, UT 


“Your products are first rate. Your Turbo-Plus products give my humble efforts a touch 
of class and speed that I would never have achieved otherwise. Obviously your products 
make Turbo Pascal a much better product.” 


Mr. L.M. Johnson * Saguaro Technical Services * Cave Creek, AZ 


SPECIAL TURBO SALE 


Get $5.00 Off Every Turbo Pascal 4 Book 
Get $3.00 Off Every Turbo C & Turbo Basic Book 


~ TURBOC 


Using Turbo C“ 


by Herbert Schildt 


For all C programmers, beginners to pros, this excellent guide 
helps you write Turbo C programs that get professional results 


[$1905 Paperback, ISBN: 0-07-881279-8, 431 pp., 7% x 9% 


Borland-Osborne/McGraw-Hill Programming Series 
$16.95 


Advanced Turbo C“* 


by Herbert Schildt 


Unveils Turbo C power programming techniques to serious 
programmers. Covers Turbo Pascal conversion to Turbo C and 
Turbo C graphics. 

32e<05 Paperback, ISBN: 0-07-881280-1, 397 pp., 7% x 9Y/ 
Borland-Osborne/McGraw-Hill Programming Series 


$19.95 


Turbo C": THE COMPLETE REFERENCE 


By Herbert Schildt Covers Version 1.5 


Programmers at every level of Turbo C expertise can quickly 
locate information on Turbo C functions, commands, codes, and 
applications —all in this handy encyclopedia. 

"324095 Paperback, ISBN: 0-07-881346-8, 850 pp.. 73% x 91 
Borland-Osborne/McGraw-Hill Programming Series 


$21.95 


Turbo Pascal" 
THE COMPLETE REFERENCE 


Covers Version 4 

by Stephen O'Brien 

The first single resource that lists 
every Turbo Pascal command, 
function, and feature, all illustrated 
in short examples and applications. 
Ideal for every Turbo Pascal 
programmer. 


$2405 Paperback, ISBN: 0-07-881290-9, 814 pp., 7% x 9% 


Borland-Osborne/McGraw-Hill Programming Series 


$19.95 


For A Limited Time Only 


ORDER TODAY! CALL TOLL-FREE 800-227-0900 


TURBO PASCAL 


Programmers 
Library 
Version 4 


Using Turbo Pascal” VERSION 4 


by Steve Wood 


Build the skills you need to become a productive Turbo Pascal 4 
programmer. Covers beginning concepts to full-scale 
applications. 


"34e05 Paperback, ISBN: 0-07-881356-5, 546 pp., 7% x 9% 


Borland-Osborne/McGraw-Hill Programming Series 


$14.95 


Advanced Turbo Pascal” VERSION 4 


by Herbert Schildt 

The power of Turbo Pascal 4 will be at your fingertips when you 

learn the top-performance techniques from expert Herb Schildt 
“$2445 Paperback, ISBN: 0-07-881355-7, 416 pp., 7% x 9% 


Borland-Osborne/McGraw-Hill Programming Series 


$16.95 


Turbo Pascal" 
PROGRAMMER'’S LIBRARY, SECOND EDITION 


by Kris Jamsa and Steven Nameroff 


Take full advantage of Turbo Pascal, and the newest versions of 

Turbo Pascal, with this outstanding collection of programming 

routines. Includes routines for the Turbo Pascal toolboxes 
Paperback, ISBN: 0-07-881368-9, 600 pp., 7% x 9% 


Borland-Osborne/McGraw-Hill Programming Series 


$17.95 


Using Turbo Basic" 
by Frederick E. Mosher 
and David |. Schneider 


Introduces Turbo Basic to novices 
and seasoned pros alike. Learn 
about the Turbo Basic operating 
environment and the interactive 
editor. 

Paperback, 
ISBN: 0-07-881282-8, 
457 pp., 7% x 9% 


Borland-Osborne/McGraw-Hill Programming Series 


$16.95 


Use Your Visa, MasterCard, 
or American Express 


®@,', 33 OsborneMcGraw-Hiill 
de 2600 Tenth Street 
WEMIM Berkeley, Calitornia 94710 


Turbo Basic, Turbo C, and Turbo Pascal are registered trademarks 
of Borland International. Copyright © 1988 McGraw-Hill, Inc 


